RESTful API Designing Guidelines — The Best Practices
Facebook, Google, GitHub, Netflix, and a few other tech giants have given developers and products a chance to consume their data through APIs and became a platform for them.
Even if you are not writing APIs for other developers and products, it is always very healthy for your application to have beautifully crafted APIs.
There is a long debate going on on the internet about the best ways to design the APIs, and it is one of the most nuanced. There are no official guidelines defined for it.
The API is an interface through which many developers interact with the data. A well-designed API is always very easy to use and makes the developer’s life very smooth.
API is the GUI for developers, if it is confusing or not verbose, then the developer will start finding alternatives or stops using it. Developers’ experience is the most important metric to measure the quality of the APIs.
The API is like an artist performing on stage, and its users are the audience.
Terminologies
The following are the most important terms related to REST APIs.
- Resource is an object or representation of something that has some associated data with it and there can be a set of methods to operate on it. E.g. animals, schools, and employees are resources and delete, add, and update are the operations to be performed on these resources.
- Collections are a set of resources, e.g. companies is the collection of the company resource.
- URL (Uniform Resource Locator) is a path through which a resource can be located and actions can be performed on it.
API Endpoint
Let’s write a few APIs for companies that have some employees, to understand more.
/getAllEmployees
is an API that will respond with a list of employees. A few more APIs around a company will look like as follows:
/addNewEmployee
/updateEmployee
/deleteEmployee
/deleteAllEmployees
/promoteEmployee
/promoteAllEmployees
And there will be tons of other API endpoints like these for different operations. All of those will contain many redundant actions. Hence, all these API endpoints would be burdensome to maintain when API count increases.
What is wrong?
The URL should only contain resources (nouns), not actions or verbs. The API path /addNewEmployee
contains the action addNew
along with the resource name Employee
.
What is the correct way?
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.
Isn’t the API now more precise and consistent?
Conclusion
The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.
HTTP Methods (Verbs)
HTTP has defined a few sets of methods that indicate the type of action to be performed on the resources.
The URL is a sentence where resources are nouns and HTTP methods are verbs.
The important HTTP methods are as follows:
GET
method requests data from the resource and should not produce any side-effects. E.g/companies/3/employees
returns a list of all employees from company 3.POST
method requests the server to create a resource in the database, mostly when a webform is submitted. E.g/companies/3/employees
creates a new employee of company 3.POST
is non-idempotent which means that multiple requests will have different effects.PUT
method requests the server to update a resource or create the resource if it doesn’t exist. E.g./companies/3/employees/john
will request the server to update or create if it doesn’t exist, the john resource inthe employees collection under company 3.PUT
is idempotent which means multiple requests will have the same effects.DELETE
method requests that the resources, or their instance, are removed from the database. E.g/companies/3/employees/john/
will request the server to delete the john resource from the employees collection under company 3.
There are a few other methods which we will discuss in another post.
HTTP Response Status Codes
When the client raises a request to the server through an API, the client should know the feedback, whether it failed, passed, or the request was wrong.
HTTP status codes are a bunch of standardized codes that have various explanations in various scenarios. The server should always return the right status code.
The following are the important categorizations of HTTP codes:
2xx (Success Category)
These status codes represent that the requested action was received and successfully processed by the server.
- 200 OK — The standard HTTP response representing success for GET, PUT, or POST.
- 201 Created — This status code should be returned whenever the new instance is created. E.g. on creating a new instance, using the POST method, should always return a 201 status code.
- 204 No Content — Represents the request is successfully processed but has not returned any content. DELETE can be a good example of this. The API
DELETE /companies/43/employees/2
will delete employee 2 and in return, we do not need any data in the response body of the API, as we explicitly asked the system to delete. If there is any error, like ifemployee 2
does not exist in the database, then the response code would not be of2xx Success Category
but around4xx Client Error category
.
3xx (Redirection Category)
- 304 Not Modified — Indicates that the client has the response already in its cache. And hence, there is no need to transfer the same data again.
4xx (Client Error Category)
These status codes represent that the client has raised a faulty request.
- 400 Bad Request — Indicates that the request by the client was not processed, as the server could not understand what the client is asking for.
- 401 Unauthorized — Indicates that the client is not allowed to access resources, and should re-request with the required credentials.
- 403 Forbidden — Indicates that the request is valid and the client is authenticated, but the client is not allowed access to the page or resource for any reason. E.g. sometimes the authorized client is not allowed to access the directory on the server.
- 404 Not Found — Indicates that the requested resource is not available now.
- 410 Gone — Indicates that the requested resource is no longer available which has been intentionally moved.
5xx (Server Error Category)
- 500 Internal Server Error — Indicates that the request is valid, but the server is totally confused and the server is asked to serve an unexpected condition.
- 503 Service Unavailable — Indicates that the server is down or unavailable to receive and process the request. Mostly if the server is undergoing maintenance.
Field Name Casing Convention
You can follow any casing convention, but make sure it is consistent across the application. If the request body or response type is JSON then please follow camelCase to maintain consistency.
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
.
Conclusion
These guidelines are based on my experience in development. I would love to know your views on the pointers mentioned above. Please leave a comment, and let me know!