In this article, we are going to discuss on the best practices of RESTful API. Before we jump on to best practices, let's first understand what is REST and what makes an API RESTful.
REST is the most common communication standard between computing devices over the internet. REST stands for REpresentational State Transfer. It is a web architectural style that defines 6 constraints for the communication. These REST constraints are collectively called as web architectural style.
Client-Server: REST applications must maintain a server that manages the application data and state. Server is responsible for processing the client's requests or user interactions and provides the response back to the clients.
Both client and server must be maintained separately.
Stateless: REST applications must be stateless. The server should not maintain any of the earlier request's data to process the current the request. The client's request should contain all the necessary information for the server to process the request. The state or session data should be maintained at the client's side.
Cacheable: REST applications mark their response data as cacheable or not. This lets clients if they want to cache the response data or not. Clients can chose to cache the response data for identical requests to improve the performance.
Uniform Interface: An application system is normally composed of several components and having uniform interface between these components is one of the REST's most defining characteristic. Roy Fielding states, “The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components.”
Layered System: The components of the REST system cannot see beyond their layer and making it visible only to the adjacent layer and hiding it from the other layers.
Code-on-demand: This constraint enables web servers to send the executable code such as plugins, scripts etc to the clients. The clients can receive the code on demand and execute it if they need it. This constraint can not be made mandatory and that is why this constraint is considered as optional.
Application Programming Interface (API) is a way for two computers to talk to each other. The most common API standard for Web and Mobile applications are REST. The API that follows the REST constraints discussed above is called RESTful API.
Most common protocol RESTful apis use is HTTP, because HTTP fulfills most of the constraints that REST architectural style defines. REST APIs organizes resources in to a set of unique URIs (Uniform Resource Identifiers). These URIs denotes different types of resources on the server.
Organize the APIs around resources
The resources are the business or domain entities used to perform necessary actions to achieve a business need. Take a look in to the below APIs. Products and Users are two separate resources and each one is represented with a separate URI.
https:
https:
Define API operations in terms of HTTP methods
HTTP protocol defines number of methods to perform certain action on resources. The common HTTP methods used by most RESTful web APIs are
GET: Retrieves a representation of the resource. The body of the response contains the details of the resource or resources. For example, to retrieve the list of orders GET /api/v1/orders is used.
POST: Create a new resource. The request body contains the details of the resource to be created. POST /api/v1/orders
PUT: Update an existing resource. The request body denotes the details of the resource to be updated. PUT is usually contains an id of the resource in the URI. For example, for updating order number 7, we use PUT /api/v1/orders/7
PATCH: Performs a partial update of a resource. The request body specifies the set of the changes to the resource. The main difference between PUT and PATCH is that PUT is normally used to replace a resource. So if the request body is missing a field, then this field would be updated with empty while PATCH is used to update only the fields that are specified in the request body.
DELETE: Delete a resource. This operations contains an id of the resource in the URI. For example, DELETE /api/v1/orders/7
Use proper HTTP status codes:
Returning a meaningful error codes to the clients is important. This increases the readability and provides the accurate information about the details o the error and making easy for debugging. Below HTTP response codes denotes when to use each one.
| HTTP Status Code | Description |
| --- | --- |
| 100 - 199 | Informational response codes - The initial part of the request has been received, and the client should proceed. |
| 200 - 299 | Successful - The client's request has been successfully accepted. |
| 300 - 399 | Redirection - The client needs to perform additional actions to fulfill the request. |
| 400 - 499 | Client error - There's an error on the client's side. |
| 500 - 599 | Server error - There's an error on the server's side. |
Exchange data in JSON format: Although REST api supports different formats for exchanging the data between client and server, the most common format is JSON. Other formats like XML and YAML lack some common procedures for encoding and decoding the data. Also different programming languages offer wide range of built in methods to parse and manipulate JSON data. the data at both Server and Client side.
{
"id": 1111,
"user": "Venkat Chembati",
"bookName": "API Design",
"quantity": 10
}
Use Nouns instead of Verbs in the path:
The HTTP method used in request determines what action to be taken. So using verbs in the path makes endpoint long and we should strictly avoid using verbs. Alway use nouns instead verbs. For example,
https://www.example.com/api/v1/getOrders - Wrong
https://www.example.com/api/v1/orders - Correct
Use Clear Naming : use plural in the api endpoint names. plural tells the consumers that we are dealing with group of resources such as /orders or /products. Be consistent using clear naming convention.
Nesting on Endpoints: When different endpoints containing the associated information, then they should be interlinked. For example, If we want to get the list of products associated to an order, then we can use GET https://www.example.com/api/v1/orders/1234/products endpoint. This makes easy to understand and debugging easy.
Filtering and Pagination: Sometimes the database gets incredibly large. Getting large amount of data in a single request from such a database reduces the performances and it is a time-consuming process. In these situations, filtering can be applied to fetch only the data that is required. For example, https://www.example.com/api/v1/products?category=books can be used to get the list of products under category books.
Similarly, pagination can be used to fetch limited number of records by sending multiple requests per each page in the UI. For example, https://www.example.com/api/v1/products?limit=25&offset=50. Here, limit indicated number of records to be retrieved and offset indicates number of records to be skipped.
API Versioning: Versioning is very important in API design. Versioning allows applications to enable backward compatibility so that clients are not forced to migrate to the next version. When there is a change or a new functionality is added to the API endpoint, we can have a new version by specifying it the URI. For example, https://www.example.com/api/v2/products denotes version v2.
Secure the API: There are different ways to secure the API. For secure transfer of data, we can use https running on SSL/TLS. Authentication and Authorization mechanism should be used for APIs that provides user specific data. Technologies such as OAuth, JWT are popular for providing authentication and authorization.
API Documentation: Maintaining a comprehensive documentation about API is a best practice to help developers and clients to understand API should be used. Clearly provide the details about the request and response payload fields and it's data type. Giving an example for each field gives clarity for the API consumers.
Practicing best practices during API design or development is very important for building robust and efficient APIs. I hope these best practices will help you to build efficient APIs and make you more comfortable during API design discussions.
