How to Design a RAML-Based REST API With Mulesoft Anypoint API Manager

RAML (Rest API Modeling Language) is based on YAML format, which is used to design REST APIs. RAML provides various features, including standardization, reusability, easy readability, and much more.

Now, we will walk through how to create REST APIs using API Manager.

Create an Anypoint MuleSoft Account

Create an Anypoint MuleSoft account and sign into the Anypoint MuleSoft platform.

Add a New API

First, go to API Manager as shown below:

Click API Manager to reach the API Manager Screen. Then, click Add New API. Fill in the details like API name and Version name. Description and API endpoint are optional.

After filling in these details, click Add.

Define the API

Next, click Define API in the API Designer.

We will be navigated to API Manager Designer, where we can start writing the RAML. We can see the documentation on the right side, depending on the RAML we are writing.

On the left side, we can see the RAML file name. By default, the file name will be api.raml. We can rename the RAML filename by right clicking on api.raml. The extension of a RAML file is always .raml. For more info Mulesoft Online Training

Test the API from API Manager

We need to enable Mocking Service for testing the API. Once we will enable the mocking service, then baseURI will be added to the RAML.

After enabling the mocking service, we can test the REST API by clicking on any of the HTTP methods on the right side of the screen. Then, click Try it!.

RAML Example

#%RAML 0.8
title: Book Service API
version: 1.0
/users:
  /authors:
    description: This is used to get authors details
    get:
      responses: 
        200:
          body:
            application/json:
              example: |
                {
                "authorID":1,
                "authorName":"Robert",
                "DOB":"21/04/1986",
                "Age":30
                }  
    post:
      body: 
        application/json:
          example: |
            {
            "authorID":1,
            "authorName":"Stephen",
            "DOB":"21/04/1986",
            "Age":30
             } 
      responses: 
        201:
          body: 
            application/json:
              example: |
                {
                "message":"Author updated {but not really"
                }
    /{authorID}:
      get:
        responses: 
          200:
            body: 
              application/json:
                example: |
                  {
                  "TotalBooks":30,
                  "Subject":"Maths,Science",
                  "Publication":"Nirvana"
                  }
  /books:
    get: 
    post:
    put:
    /{bookTitle}:
      get:
        queryParameters: 
          author:
            displayName: Author
            description: The Author's Full Name
            type: string
            required: false
            example: Michael Lynn
          publicationYear:
            displayName: Publication Year
            description: Year of Publication
            type: number
            required: false
            example: 2010
          rating:
            displayName: Rating
            description: Average Rating of book submitted by users (1-5)
            type: number
            required: false
            example: 3.5
          isbn:
            displayName: ISBN
            description: ISBN Number of Book
            type: string
            maxLength: 10
            example: 1234567
            required: false
        responses: 
          200:
            body: 
              application/json:
                example: |
                  {
                  "id": "123",
                  "title": "API Design",
                  "description": null,
                  "datetime": 1341533193,
                  "author": "Mary"
                  }
      put:
      delete:
      /author:
        get:
      /publisher:
        get:

Including Example Responses

Simulating calls to the API is a critical design task that helps you troubleshoot problems and demo the API to prospective users even before you have implemented it. Valuable feedback can result from a demo and help you improve the API. To simulate calls to the API, you include the following things:

A JSON example of data an actual implementation of the API would return
An HTTP status codes the API returns on success or a failure message.

You use the mocking service in API Console to provide a base URI for the unimplemented API. When you make a successful call to the API, the mocking service returns the status code 200 and example.

To get in-depth knowledge, enroll for a live free demo on Mulesoft Training