RAML stands for Restful API Modeling Language. Specifically, RAML is an initial approach to designing a document before implementing the business logic. It includes all the necessary information about the API, such as the resource name, required method, request to send to the target system, response to show the user, and error codes to display in case of any issues. All these details are contained within RAML.
We write or design an API Specification in Mulesoft’s Anypoint Platform’s Design Center.
Steps to design RAML:
To design any RAML, we need to follow a few steps:
1. Resource Path
2. Method
3. Request
4. Response
5. Error Responses.
Resource Path:
In simple terms, a resource path is a part of an endpoint URL that identifies a specific resource. For example, in https://api.amazon.com/users, “users” is the resource path.
The URL may also contain parameters (query parameters, URI parameters) to specify additional details.
HTTP Method:
Some of the most frequently used HTTP methods include:
1. POST
2. GET
3. PUT
4. PATCH
5. DELETE
Post Method Use Case:
Let’s consider a scenario where a company is onboarding new employees, and the HR’s task is to enter their details into the database system. The HR will input the employee’s details into the database using the POST method in HTTP to insert new information.
POST Employee Data:
As discussed in the previous steps, designing a RAML is quite simple. The key steps to follow include defining the resource path, method, request, response, and error codes.
In the above example, “employee” represents our resource path, which must always begin with the ‘/’ symbol.
After the method, there is something called the Body. Generally, we pass our request using the Body parameter.
We need to specify the format we are providing to the Body parameter, such as “application/json” or “application/xml”. After “application/json”, there is an example, indicating that we need to provide our request data accordingly.
After receiving responses, there is a specific number, such as “201”, which essentially defines a successful response. This is known as an “HTTP success code.”
In the image above, there are numbers such as 400 and 401, which are HTTP error codes. You can explore and learn more about them on https://http.cat.
Get Method Use Case:
Let’s assume that the HR needs to retrieve the details of all employees from the database. To implement this functionality using HTTP methods, we utilize the GET method.
GET Employee Details:
We have already covered how to write a RAML for the POST method. Now, let’s explore writing a RAML for the GET method. There are only minor similarities between the POST and GET methods.
For the GET method, we do not write any request; we simply fetch the data from the target system.
When fetching data from the target system, we may utilize parameters such as Query Parameters and URI parameters in conjunction with the Get method.
Query Parameter:
Let’s consider the same use case we discussed for the Get method. As we all know, in an organization, there are various roles such as developers, administrators, leads, managers, and more.
Now, HR wants to retrieve all the employees whose role is a developer. To meet this requirement, we need to utilize query parameters.
URI Parameters:
Now that we have a clear understanding of query parameters, let’s delve into what URI parameters entail. Let’s consider the same example: the HR department wants to retrieve the details of a single developer (previously, we retrieved details of all developers from various roles). Despite query parameters allowing HR to access all developers’ details, the specific need is to retrieve details of only one developer. This particular requirement necessitates the use of URI parameters. While an organization may have numerous developers, each developer is assigned a unique empId. Retrieving details of a specific developer can be accomplished by utilizing this empId.
Request:
In general, a request refers to the data of an entity. As discussed in the above example of the POST method use case, every employee has details such as name, age, phone number, and address. While each employee in the organization holds this data, the values will vary.
[
{
“name”: “John”,
“age”: “25”,
“address”: “NY”,
“phoneNumber”: “03456112”,
“role”: “Developer”
},
{
“name”: “Watts”,
“age”: “32”,
“address”: “DC”,
“phoneNumber”: “09349876”,
“role”: “Adminstrator”
}
]
Responses:
When the HR inserts employee data into the database, they need to confirm whether the insertion was successful. This confirmation is received as a response from the database or target system, indicating the success or failure of the insertion process, known as a “Response.”
Error Codes:
During the process of inserting (Post), fetching employee details (Get), updating employee details (Put and Patch), and removing employee details (Delete), HR may encounter errors. To precisely identify the errors that occur, we define specific HTTP error codes.
The blog has given a basic understanding of RAML with an example. For more such information or queries, please reach out to [email protected].