Data Formats in RAML Specification - DZone

What Is RAML?

RAML, which stands for "RESTful API Modeling Language," is a YAML-based language for describing RESTful APIs. It is a blueprint before developing an API that makes it easier for both developers and stakeholders to understand the API's structure and behavior.

What Are Data Types?

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

Built-In Data Types

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

• String: Represents textual data.
• Number: Represents numeric values.
• Integer: Represents whole numbers.
• Boolean: Represents true or false values.
• Date-Only: Represents a date without a time component.
• Time-Only: Represents a time without a date component.
• DateTime: Represents a date and time.

User-Defined Data Types

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

Use Case

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

Goals

• Create a RAML Specification.
• Create Datatype files.
• Create a resource /user and add the required information.
• Verify endpoints using mocking services.
• Publish to Exchange.

Step 1: Create RAML Specification

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

Step 2: Create DataType Files

• Create a folder “dataTypes” in the files section.
• Create a folder dataTypes and add request and response data types as 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 the sample 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 above RAML specification, “|” symbol is used in the body type, which means that it can accept either jsonTypeOne or jsonTypeTwo. In addition to this we can also send xmlType.

Step 4: Verify Endpoints Using Mocking Services

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

Step 5: Publish to Exchange

Once the RAML specification is ready and verified using mocking services, you can publish the specification to the Anypoint Exchange. Publishing to Exchange will enable your users to verify the endpoints from their end before starting the implementation.

Summary

In conclusion, a single resource can have different data types with different formats and users can implement them as per their requirements.