In the previous tutorial, I introduced you to RAML to define API spec. In this tutorial, I will guide you in more detail how to define request URL with RAML!

As an example for this tutorial, first, I will create a new .raml file with information about the student management API including adding, deleting, editing, searching with the following initial content:

We will define some requests as follows:

• GET /students to get a list of students
• POST /students to add new students
• PUT /students/{id} to update a student with the id passed in the request
• DELETE /students/{id} to delete a student with the id passed in the request
• GET /students/find-by-name?name=<student-name>
• GET /students/find-by-ids?id=<id1>,<id2>

With requests like these, you can define a root request “/students” as follows:

Just imagine a request URL will be divided into several levels from left to right. For example, request /api/students/find will have 3 levels: api, then students and then find. These levels are separated by a “/”. Each level will be a level in the .raml file in that order, so in my example above, the root request for all requests would be “/students”.

For this root request, we have 2 requests, GET and POST, to get all students’ information and add new students, so you just need to declare these requests as follows:

You can add a description for each request if you want, for example:

Next, we have 2 requests with /students/{id} with PUT and DELETE HTTP methods, used to update and delete information of a certain student. Since we have already defined the root request with “/students”, now you only need to define these two new requests as follows:

You can define more information of the path parameters, information about the purpose of the path parameter, what the data type is, an example of their value. To do this, we will use the uriParameters section. For example, I can define information for path parameter {id} in the above example as follows:

For the request /students/find-by-name?name=<student-name>, we need to define an additional section /find-by-name with the root request as “/students” as follows:

The HTTP method of this request is GET and I have also added a description for this request.

For this /students/find-by-name request, we have an additional request parameter named name. We can define this request parameter information as follows:

As you can see, I use the queryParameters section to specify information for all request parameters of the request. The request parameter in this example has data type String. You can define whether this request parameter is required or not using the “required: false” attribute or use the question mark as follows:

In my example, the request parameter name is required!

For requests with matrix parameters like /students/find-by-ids? id=<id1>,<id2> , you can define that matrix parameter with the type of array. Examples are as follows:

The full contents of the .raml file of the example in this tutorial are as follows: