Build RAML-Based API Specification Using MuleSoft Platform

In earlier blogs, we saw many languages like Python, C++, Java, and so on that developers use to develop applications that we use to retrieve and insert data. In this blog, we shall learn about RAML which is a language used to create API specification.

Introduction to RAML

RAML stands for RESTful API Modelling Language. It is a YAML /JSON-based modeling language. The language is simple and structured, which is readable by both humans and computers. We use HTTP methods to call the resources while creating API specifications. 

RAML is very helpful as it allows the developers to define API endpoints, payloads, query parameters, HTTP methods, and responses to the request sent. These in-built features help the developers to design, and test APIs easily. MuleSoft is one such platform that provides anypoint platform, in which we can access the Design Center, wherein we could build APIs using RAML. 

Firstly, we should sign in/ sign up to Anypoint platform by MuleSoft. The account is accessed for a limited time period, say 1 month.

The Design Center in the platform looks like this:

Now that we know the components of a design center, let us discuss the components in detail. 

• File browser usually contains the documents, mostly RAML/JSON schemas and examples which are used during the construction of an API specification. The path of these files is copied and added to the resources using a valid syntax '!include'.
• The Shelf contains in-built features like parameters, docs and HTTP methods, that are used while creating APIs. We can easily use these functions.
• The Editor is the main area where the whole process of API creation takes place. We shall use the functions from the shelf accordingly.
• API console helps us to test the API specifications using the mocking service. 

Getting Started With RAML

Let's now discuss how to create an API to retrieve and add data using an example of employees details in an IT company using RAML in the design center.

First, go to the design center in anypoint platform and create a new API specification with a proper name related to the API you are creating.

We need to create a separate RAML file in file browser that contains data types of the details we are going to access in the API. 

Now from the above example, we will create a datatype file for the details of the employees.

NOTE: Data types file is usually written in RAML so that we can give specifications.

#%RAML 1.0 datatype

properties:
  ID?:
    type: integer
  name:
    type: string
  city:
    type: string
  designation:
    type: string
  phonenumber:
    type: integer
  address:
    type: string

Attach the above data types file using types by copying the path of the file. 

NOTE: Use '!include' to attach the file.

DESIGN: Moving on, we can add the resources name with a forward slash(/) (for example: /employee). We can use the HTTP methods to request the response from the portal. If we want to retrieve data, we use the get method. Or else if we want to create data, we use the post method. Later, we can call functions appropriately from the shelf like adding query parameters to check the responses for that request. Enum is used for choosing between options. Responses are obtained using an HTTP method code 200 which is used to receive data and HTTP method code 201 used to add data to an API. In the end, add example files to the API for the display of details.

MOCKING: This mocking service is used to test the methods by sending a request. If the response is 200 ok, then the request is successful. The API specification is tested using this.

NOTE: If the response is 4xx series then the request sent is an error. Please check the code.

Let's now check the example RAML code of employees in an IT company:

In the above RAML code, we are calling a resource employee under which we give a get method to retrieve the information of the employees working in that company. We are also calling the resource employee using UI parameter ID {id}. Under this resource we are giving two methods, get and post.

#%RAML 1.0
title: employees-sys-api

types:
  employeeData: !include/employee-datatypes/employee-datatype.raml

/employees:
  get:
    queryParameters:
      city:
        required: false
        enum:
          - LAX
          - TX
          - NYC
    responses:
      200:
        body:
          application/json:
            type: employeeData
            examples:
              output: !include /examples/employee-examples.json
      
  /employee/{id}:
      get:
        responses:
          200:
            body:
              application/json:
                type: employeeData
                examples:
                  output: !include /examples/employee-examplesNoID.json
            
      post:
        body:
          application/json:
            example: !include /examples/employee-examplesNoID.json
        responses:
          201:
            body:
              application/json:
                example:
                  message: Employee added but not really

As we discussed earlier, we can add examples for each HTTP request. A sample is shown below, follow that for better understanding.

NOTE: Use JSON language but not RAML for examples.

{
  "id": "345",
  "name": "john",
  "city": "LAX",
  "designation": "manager",
  "phonenumber": "8765987698",
  "address": "45-street,Califonia-54"
}

You have successfully designed your API specification using RAML!! You can now publish it in exchange which is a portal to display all APIs both privately and publicly. 

Conclusion

RAML is a powerful tool used nowadays to create APIs. We can create our own RAML using the design center provided by the MuleSoft platform. In my next blog, you will see how this API specification can be published in exchange so that the API is discoverable. Hope you like my blog. Do leave a comment about your views on this topic and share it. Happy knowledge.

Thank you.