Designing APIs/RAML With MuleSoft

Everyone is talking about APIs. All new apps/services have some kind of API and almost every app uses at least one API. What is an API? In layman terms, an API provides an interface between two applications so that they can talk to each other. 

RAML was introduced in 2013 and received great support from MuleSoft, Box, CISCO, AngularJS, and lots of other leaders in the technology space. RESTful API Modeling Language (RAML) is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful APIs, providing a simpler way to design APIs.

You should be asking these questions to yourself while writing APIs:

• What should be the input and output parameters for my API? It purely depends on who is the consumer of the API.
• Are you designing the API for customers, or will it be consumed within the enterprise? Will it be deployed on DMZ or inside the enterprise firewall? It helps you to decide whether the API is going to be public or private.
• Does API require a RAML contract? A contract would be preferred, as it provides the specification of the API.

Once you have the answers to these questions, you can start on the design of the API. It helps in the long run if you get the answers to these questions before designing your API.

Where Should We Write/Design RAML for the API?

MuleSoft API designer provides a web-based graphical environment for designing, documenting, and testing APIs. API designer makes it easy to engage API consumers at multiple stages in the design process. You can design your APIs and test it there itself using a mocking service with in API designer.

Let's see how Mulesoft makes your life easy.

API Designer 

In the API Designer, you can add a new API by just clicking on "Add new API." It will ask for the API name and version name.

Start the design of the API by providing API Name and version name. 

Once you fill in the above, Anypoint Platform will show you the API administration page, which includes the API definition, portal, and status of the API.

You can start the design for your API (writing RAML) under "API definition."

Go to Edit in API Designer and start writing the API. This is a sample API:

Let's start by providing the title, version, baseURI, and RAML version. We are using RAML 1.0.

This is called the ROOT of your RAML and contains the basic information of the API. The baseUri is the URL where the API will be hosted.

Next, we will design the request. Here we will define the resource, methods and query parameters.

Resource- /flights

First Method- get

Query Params - destination and airline

We can see that API Designer is building an interface for us in parallel at the right side for the mocking service.

The last part for any API design is the response. The response includes the responses, response code, body, content type, and response message.

For this blog, I am using response code 200 for a successful response.

We can use the response from an example as above. We can also use a schema to define the response structure or from a data model introduced in the new RAML 1.0. 

For RESTful APIs, developers can define all different status codes for the API responses.

Testing Using a Mocking Service

A mocking service can be used to mock the API and test it. If we look on the right side corner, the mocking service is OFF by default. We need to scroll that button to the right and the mocking service will be ON.

Once we scroll the mocking service button, the baseUri given by us will be commented and the mocking service URI will appear in the API. It is a great inbuilt feature of API Designer.

We can expand the GET method to mock this service.

Once we hit the Try it button, we need to fill the required parameters, like query parameter in this case, and then hit the GET method button.

The API will send the configured response. For this API, we have used an example.    

By this time, we understand that designing an API in API Designer is really easy. 

The API designer provided by MuleSoft is a great capability, as it provides the option to design your RAML and test it without writing a single line of code. 

With this article, you have an idea how RAML can be defined and is supported by Anypoint Designer in MuleSoft. Why not start using RAML with MuleSoft? Mule's Anypoint Studio can be used to import the RAML and it can generate REST interfaces for you, which is another great capability from MuleSoft.

MuleSoft has recently added the OpenAPI specification into their API kit. MuleSoft provides a playground website for everyone to play with the API modeling framework and its capabilities.

Hope you enjoyed reading this article!