RESTful API - Best Practices

RESTful API Designing Guidelines — The Best Practices

API Endpoint

Let’s write a few APIs for companies that have some employees, to understand more.

The /companies endpoint is a good example that contains no action. But the question is: “How do we tell the server about the actions to be performed on the companies resource and whether to add, delete, or update?”

This is where the HTTP methods (GET, POST, DELETE, PUT), also called verbs, play a role.

The resource should always be plural in the API endpoint and if we want to access one instance of the resource, we can always pass the ID in the URL.

• The method GET path /companies should get the list of all companies.
• The method GET path /companies/34 should get the details of company 34.
• The method DELETE path /companies/34 should delete company 34.

In a few other use cases, if we have resources under a resource, e.g employees of a company, then a few of the sample API endpoints would be:

• GET /companies/3/employees should get the list of all employees from company 3.
• GET /companies/3/employees/45 should get the details of employee 45, who belongs to company 3.
• DELETE /companies/3/employees/45 should delete employee 45, who belongs to company 3.
• POST /companies should create a new company and return the details of the new company created.

Searching, Sorting, Filtering, and Pagination

All of these actions are simply the query on one dataset. There will be no new set of APIs to handle these actions. We need to append the query params with the GET method API.

Let’s understand how to implement these actions with a few examples.

• Sorting — In case the client wants to get the sorted list of companies, the GET /companies endpoint should accept multiple sort params in the query.
  E.g. GET /companies?sort=rank_asc would sort the companies by rank in ascending order.
• Filtering — For filtering the dataset, we can pass various options through query params. E.g. GET /companies?category=banking&location=india would filter the company’s list data with the company category of banking and where the location is: India.
• Searching — When searching the company name in the company list, the API endpoint should be GET /companies?search=Digital Mckinsey.
• Pagination — When the dataset is too large, we divide the data set into smaller chunks, which helps in improving performance and it is easier to handle the response. E.g. GET /companies?page=23 means to get the list of companies on the 23rd page.

If adding many query params in GET methods makes the URI too long, the server may respond with 414 URI Too long HTTP status. In those cases, params can also be passed in the request body of the POST method.

Versioning

When your APIs are being consumed by the world, upgrading the APIs with some breaking change would also lead to breaking the existing products or services using your APIs.

http://api.yourservice.com/v1/companies/34/employees is a good example, which has the version number of the API in the path. If there is any major breaking update, we can name the new set of APIs as v2 or v1.x.x.