Introducing about RAML

You all have probably worked with RESTful Web Service, but maybe not much have heard about RAML (RESTful API Modeling Language), a specification that helps us define RESTful Web Service APIs. In this tutorial, let’s learn about it, to know what it is and what it can do for us.

First, as I said, we use RAML to define APIs for the RESTful Web Service, what their purpose is, how many APIs we need to implement, what HTTP methods they use, what are the request parameters, how their response body is and we can also add some examples of request parameters, response body for our APIs.

We define the RAML specification in a .raml file. Now, I will take an example of the contents of a .ram file as follows:

This is a .raml file that defines APIs for a student management system, including retrieving information from all students, retrieving student information by ID, and deleting student information by ID.

At the top of this file, you can see that we have some lines describing our APIs, what the version RAML specification is, what baseUri is, what it is for and what version it is:

As you can see, the title defines the purpose of our APIs, in this example, for managing student information. BaseUri is used to define the root URL for the API, the version here is the version of our API. From this information, you can get an overview of our APIs.

The rest of the .raml file is a detailed definition of our APIs.

As you can see, each API will be defined with the directory tree structure.

The first is the definition of resource or request URL.

Request URLs will start with a “/” character and you can easily distinguish them as non-indent lines.

In the above example, I have defined three request URLs:

  • /student/{ID} with GET HTTP method
  • /student/{ID} with  DELETE HTTP method
  • /students

These are some request URLs that we need in our API. In the first request URL, I defined a URI parameter named ID. With this URI parameter, I have a section below the request URL to describe it:

Here, I have described the URI parameter as the student ID, the string data type, and an example of its value.

In addition to the string data type, RAML also allows us to define the object data type, integer data type, and some other data types.

For each request URL, we will need to define the HTTP method for each request URL.

In our example above, two of /student/{ID} requests URLs were defined with two HTTP methods GET and DELETE. RAML supports us to define all HTTP methods like GET, POST, DELETE, PUT, etc.

Next, for each HTTP method, we can define the return data type with each HTTP status code.

As above example, for each request URL with a return HTTP status of 200, I defined the response body for each request as an application/json.

You can define the response body according to your wishes, depending on the response status code that you want.

And with that, I also added some examples of the return data for each request URL as a JSON string.

The RAML structure of the API definitions allow us to visualize the APIs very well, don’t we?

Add Comment