Best Practices of Developing REST API
API’s or the Application Programming interface is the most common way of exposing the data to the external software components, operating systems, or Micro-services. REST API’s become so common with the popularity of mobile applications as well as due to the user-friendliness and ease of understanding for the developers to code on it.
REST API development is there since the early 2000s but still don’t have a real standard or a guideline for API development. Instead, API developers had different conventions and approach to come up with a proper solid API. In this article, Let’s discuss several best practices we can follow and use when developing REST API.
Proper usage of naming conventions
A REST API mainly contains 2 parts.
- An Endpoint URL : This is a URL which use to access the resource of the API.
Eg. https://mydomain/user/123?format=json
This contains the a domain, port, path, and/or query string.
- The HTTP method : Used on any endpoint which map to application create, read, update, and delete (CRUD) operations (GET, POST, PUT, DELETE)
Usually, It use Plural nouns for endpoint names, While the Verbs are used for the HTTP methods.
If you have a resource to get the list of users, We can define the endpoint name as below. Avoid using verbs such as getusers, createuser…etc when defining endpoints
Eg. To get the list of users GET https://mydomain/users
Eg. To get a specific user GET https://mydomain/users/{user_id}
API Versioning
During the lifetime of an API. It will alter the existing operations, Data structure changes happen, New methods getting added, Bug fixes. Sometimes this is a frequent task. When these changes getting happens, What happens to your current API consumers. It is very hard for current consumers to adopt such rapid changes. In this kind of scenario, versioning comes handy.
Assume a scenario like following.
There is an academic institution where they exposing their academic courses via an API. Over time they decided to change the response module adding more information and the names of some of the fields. In such a case, Other 3rd party websites that using this API, Will no longer able to use this due to this change. To overcome this, We can do something like this.
- Current
https://mydomain/v1.0.0/courses
- New API
https://mydomain/v2.0.0/courses
Like this we can expose the same API resource with a different version. Defining API version may vary from organization to other. For a example, Twitter use the release date as the version number. While Facebook use a numbering system such as v1.0.0, v1.0.1..etc.
Validation, Handling errors and use proper status codes
This is a very critical factor needed to consider when developing an API. It is mandatory to validate the request body, headers, URL parameters, and query parameters…etc upon an API call. Considering the security issues such as SQL injection this is something must.
Then it’s mandatory to use the proper status codes appropriate for each scenario. For example, after validating the request body, If it’s not matched with the intended request body, The response should be like 400 Bad request. But sometimes, there are API’s which responding 500 internal server error or 200 OK saying there was an error. We have to handle them properly. This website contains the list of HTTP status codes and it’s usages.
Throttling, Rate limiting
This is something very least addressing when developing an API, But this is an extremely important factor for a good healthy API.
There are so many factors involved in the performance of the API such as DB, Server where the API running, network…etc. Each of these components is having a threshold where it could handle the maximum limit. If the API is overwhelmed and met these thresholds, it will decrease the performance of the API eventually leads to business impact.
Therefore, It’s better to perform load tests and identify the best suitable number, and throttle the requests if the limit is made. And if this number needs to be improved then we have to consider scaling.
Filtering, sorting, paging, and field selection
This is useful when the an API response with a large collection of data such as list of items in a e commerce website.
Depending on the situation, The API consumer might need to limit, sort the response depending on the use case. Most common example for this is, We have seen the page navigation bars or limit result drop downs.
And also, Sometimes in a large collection, We might only need several fields in the response. In such cases these feature comes handy. This will avoid unnecessary load on processing response as well as better utilization of network bandwidth.
Secure API
It is a good practice to use a security layer on top of everything even for the simplest API. We can use basic authentication or Oauth2. With the oauth2 it’s capable to use more fine-grain access by using the scopes. This will allow preventing access to the API from unintended parties and some common security threats.
And also, it is recommended to use HTTPS when using the REST API’s Since data is shared between parties using plain text, The middle party could easily read the messages if they can intercept the communication. But using HTTPS, It will use encrypted communication and it is much complex to compromise.
API Documentation
This is the most essential thing for the API’s consumers. It is necessary to document all the technical and functional behaviors properly. There are different ways of exposing this. Some organizations that use OpenAPI/Swagger Specification have automated the documentation process. While some are having a proper public website descending all the bits and pieces.
For example, Twitter publishes all API documentation in a separate website explain everything from the scratch. While WSO2 use Swagger automated the documentation to explain regarding the product API’s.
These are several and some key best practices to be considered when developing a Good API. With the availability of the API Management solutions such as WSO2 API Manager. We can front the API Management solution to take care of some of the above responsibilities.
Thanks and Happy Coding
