Design API Specification in Mulesoft RAML With Example

In this article, you will learn what an API specification is and how to Design a RESTful API specification using AnyPoint Platform > Design Center – Mulesoft RAML Example.

What is API Specification ?​

An API Specification is a blueprint for APIs which provides a detailed understanding of how an API behaves, what kind of request an API is accepting, what kind of response it is giving, and what are the mandatory fields/datatype, etc…

Let’s see an example of how to design RESTful API specification in  mulesoft raml example.

Steps for Designing RESTful API Specification in Mulesoft RAML Example :

Step 1: Open www.anypoint.mulesoft.com in your favorite web browser and click on Design Center.

Step 2: Now, In the Design Center Click on Create New > New API  Spec as shown in the below screenshot

Step 3: After Clicking New API Spec then it will appear like the below screenshot

Now, Please Enter your API Specification Name. Actually,  Design Center will allow us to write RAML in 2 modes, the First mode is Writing From Scratch with Interactive documentation support, Also we feel a little bit of coding experience in this mode, and the Second One is through a visual interface guide.

Now we can move forward with the first mode.

After choosing, click on Create API Spec

Step 4: Now, We are going to write our first API specification as shown in the below 

#%RAML 1.0
title: MyFirstSpecification
version: v1
description: An API Having One Resource which will fetch all the user details.
types: 
  User:
    description: Single User Data
    type: object
    properties: 
      email: string
      name: string
      phone: string
  UserList:
    description: List of customers
    type: UserList[]
/users:
  get:
    description: Get the list of all users
    responses:  
      201: 
        body: 
          application/json: 
            type: UserList

Each RAML file must start with #%RAML, the title consists of the name of the RAML file. Here, version: v1 means the version of the API that we are developing( It is not the RAML Version).

From line no. 5 to 15: It is defining some types, First one is User which is a type of object having some properties like email, name, phone…  and this User type will return only single-user data and the Second one is UserList which is a type of user-array and this will return an array of users data.

From line no. 17 to 24: /users is the unique name given for identifying a resource, get is an example for request method like post/put/delete… And this resource is giving response with a status code like 201 and a list of users in the JSON format.

That’s it, Now we need to publish it to API exchange So that it is available to everyone in your organization.

Now, Enter Asset Version and then Click On Publish to Exchange

Finally, We Successfully Created and published our first API Specification to API Exchange.

RAML Mulesoft Documentation

If you have any questions or suggestions about Design Center, API Specification, or Mulesoft Anypoint Platform, please feel free to leave a comment below.