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 API specs for the RESTful Web Service. 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 API specs for RESTful Web Service, what is its purpose for, how many request URLs (aka resources) we need to implement, which HTTP method they use, what are their request parameters, how are their response bodies and we can add some examples of request parameters, response bodies for those resources.

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 API specs 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 API specs, 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 API specs, in this example, for managing student information. baseUri is used to define the root URL for the resources, the version here is the version of our API specs. From this information, you can get an overview of our API specs.

The rest of the .raml file is a detailed definition of the resources in our API specs.

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

Request URLs will start with the character “/” and if one of them starts with the same value, we can inherit that same value to define request URLs. In the above example, I have defined 3 request URLs which are:

• /students with GET HTTP method
• /students/{id} with GET HTTP method
• /students/{id} with DELETE HTTP method

These request URLs all start with “/students”, so we can inherit this value, no need to declare it individually.

For the first request, we define the request to get all student information.

This is a GET request, RAML supports us to define all HTTP methods such as GET, POST, DELETE, PUT, etc.

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

As the example above, for each request URL, with the return status of 200, I have defined the response body for each request in the form of application/json.

You can define the response body according to the response status code you want!

We can add some examples of the response body for each request URL as a JSON string.

In the second and third request URLs, I have defined a URI parameter named id. With this URI parameter id, I will have a section below the request URL to describe it:

Here, I have described the URI parameter as the student’s id, the data type is a string, and an example of its value. This URI parameter can be used for these 2 URL requests!

In addition to the string data type, RAML also allows us to define data types object, integer, and some other data types as well. You can refer to the tutorial Data types in RAML for more information.

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