Data formats in the RAML specification

What is RAML?

RAML, which stands for “RESTful API Modeling Language”, is a YAML-based language for describing RESTful APIs. It is a pre-development blueprint of the API that makes it easier for developers and stakeholders to understand the structure and behavior of the API.

What are data types?

Data types are used to specify the structure or type of data that is exchanged between the client and the server. This allows validating request and response payloads and maintaining payload standards.

Built-in data types

RAML includes several built-in or primitive data types that represent basic value types. Some of the common built-in data types include:

• Series: Represents textual data.
• Number: Represents numeric values.
• Whole number: Represents whole numbers.
• Boolean: Represents true or false values.
• Date only: Represents a date without a time component.
• Just time: Represents time without a date component.
• Date time: Represents the date and time.

User-defined data types

You can also define custom or user-defined data types in RAML. These types can have certain properties with their own data types. This allows you to create structured, reusable components for your API.

Use case

Create a single resource RAML with different data types and formats and publish it to Exchange.

Goals

• Create a RAML specification.
• Create data type files.
• Create a resource/user and add the necessary information.
• Verifying endpoints using mocking services.
• Publish to Exchange.

Step 1: Create a RAML specification

• Create an account on the Anypoint platform.
• Go to the Design Center and create a RAML specification.
• Give your specification an appropriate name.

Step 2: Create the DataType files

• Create a “dataTypes” folder in the files section.
• Create a dataTypes folder and add request and response data types as shown below.
  • jsonDataTypeOne
  • jsonDataTypeTwo
  • xmlDataType
  • responseDataType

jsonDataTypeOne

#%RAML 1.0 DataType

type: object
properties:
 name:
   type: string
   example: "Caroline"
 age:
   type: number
   example: 22
 active:
   type: boolean
   example: true

jsonDataTypeTwo

#%RAML 1.0 DataType


type: object
properties:
 name:
   type: string
   example: "Caroline"
 age:
   type: number
   example: 22
 address:
   type: string
   example: "145 Main St, Dallas, TX"

xmlDataType

#%RAML 1.0 DataType

type: object
properties:
 top:
   type: object
   properties:
     abc:
       xml:
         attribute: true
         name: abc
     xmlNamespace:
       xml:
         attribute: true
         namespace: http://google.com
     node:
       type: string
       example:
         <xml>
           <top abc="123" xmlns="http://google.com">
             <node>12345</node>
           </top>
         </xml>

responseDataType

#%RAML 1.0 DataType

type: object
properties:
 message:
   type: string
   example: "success"
 payload:
   type: object
   example: 

Step 3: Create resource/users

Below is an example RAML specification.

#%RAML 1.0
title: test

types:
 jsonTypeOne: !include dataTypes/jsonDataTypeOne.raml
 jsonTypeTwo: !include dataTypes/jsonDataTypeTwo.raml
 xmlType: !include dataTypes/xmlDataType.raml
 responseType: !include  dataTypes/responseDataType.raml

/users:
 post:
   body:
     application/json:
       type: jsonTypeOne | jsonTypeTwo
     application/xml:
       type: xmlType
   responses:
     200:
       body:
         application/json:
           type: responseType

In the RAML specification above, “|” symbol is used in the body type, which means it can accept either jsonTypeOne or jsonTypeTwo. We can also send xmlType with this.

Step 4: Verify endpoints using Mocking Services

In the above image we can see that it accepts both json and xml type. It also allows the user to choose between jsonTypeOne or jsonTypeTwo.

Step 5: Publish to Exchange

Once the RAML specification is ready and validated using mocking services, you can publish the specification to Anypoint Exchange. Publishing to Exchange will allow your users to verify endpoints on their end before starting deployment.

Abstract

In conclusion, one resource can have different types of data with different formats and users can implement them according to their requirements.