This is second in the series and follow up of my last blog, SF’s Top 7 Best Practices for REST API’s,we cover some good practices to follow to gain the maximum of the REST API’s.

In this article, I am highlighting some more “good” to have points – which when combined with the magnificent seven will ensure we use REST API’s most efficiently:

 

I) Version the APIs

If there is any change in the API which impacts input, output or expectation out of the API, then it can impact its clients (e.g. Mobile app, web app, etc). If developers of client are in-house and coordination is possible between client developers and api developers, then there is nothing much to worry. But, there can be situations where client developers are distributed across multiple organizations, for instance developers using Facebook API, or, where client developers are working with some other organization – such as product owner outsourcing UI and API to two different teams/vendors.

In the first case of multiple organizations using API, API should be versioned in such a way that multiple versions of API can coexist in the same deployment. Its routes could begin with ‘api/v1’, ‘api/v2’, etc to demarcate the multiple versions. And, before stopping support for an API version, veritable time should be given to client developers to upgrade the API.

In latter case when client developers are working with some other organization, it is best to have separate deployments of each version of REST API. And, client developers could keep connecting to the version of API with which they are compatible with. When client developers have changed the code to become compatible with the latest API, deployment of older API version can be removed. In this case there is only one version of the API active. The old deployment is kept as it is to not stop the work of client developers till they port to the latest release.

II) Optimize for performance

It is important to note that an API execution takes just a few milliseconds, which means that if there is need for any high CPU or IO intensive work, it is better to take it off the execution of API. There is need for API to export a report, report data could be huge. Therefore to generate report, it is better to trigger report generation and returns 202 http code depicting – ‘that request has been accepted for processing, but the processing has not been completed’. As a return of API call, client should also receive report ID to be able to access the detailed report using report ID.

Another possible performance improvement is to use caching engine like redis. This ensures database isn’t hit again and again for same data, and helps in subsequent calls to API for same data. It can also help in reducing load on database in case of multiple concurrent users to the API.

III) Use transaction management right from start

There has been situations where developer may forget to place a database transaction management logic – in such a situation an error in the API will show and all data changes in API are rolled back!

While one can take steps to avoid it, lack of foresight in this situation causes tedious repercussions. And the cost to the project or development lifecycle can be significant – the cost one can say is directly proportional to the lateness of the stage this transaction management logic is added. Hence it is very important to introduce transaction management early in the system so as to reduce the overall costs. . It doesn’t matter if it is the GET request or PUT/PATCH/DELETE/POST request, it is easier to catch it this way if any developer is trying to update DB in GET request!

IV) Use linting plugins for IDE to catch errors upfront

IDE linting plugins are very important for interpreted languages such as JavaScript, PHP, et. al. These plugins have default rules which can be customized or used as is – depending on your need. The idea for using these plugins is that it can save us a lot of time during development processes. The ‘plugins’ find code that are not meeting the requisite of the rules that have been set – giving warnings before they can be unit tested.
Use of such plugins lessen the probability to have too many errors and creating an efficient process. One such plugin we have used for NodeJS is ESLint.

V) Use ORM with caution

Object-relational mapping or ORM is extremely helpful in abstracting SQL from developers, so, developers need to make a call to ORM, which in turn – internally generates SQL and then makes call to DB. Based on the response from DB, ORM will internally convert data into structured objects before passing it to the developer. In essence this is good and creates a placebo BUT there are situations where SQL query generated by ORM are not the most efficient, this could be because of any of the following reasons:

  • parameters passed to ORM
  • configuration
  • a bug in ORM

so it becomes important to log raw query generated by ORM and doing explain plan on it to check whether it uses proper indexes and joins as per our needs.

VI) Use threat modeling

According to the Open Web Application Security Project (OWASP) Foundation, threat modelling is defined as, “Threat modeling is an approach for analyzing the security of an application. It is a structured approach that enables you to identify, quantify and address the security risks associated with an application.”

So, to reiterate and pull from our experience use of one is highly recommended and we recommend STRIDE, which is an acronym for:

  1. Spoofing
  2. Tampering
  3. Repudiation
  4. Information Disclosure
  5. Denial of Service
  6. Elevation of Privilege

The STRIDE pattern is widely used for threat modeling; listing and classifying threats and then finding ways to avoid the attacks.

Thus we conclude our final blog on REST API’s. We hope that you liked our Best Practices as well as the additional bonus tips in building REST API’s. Reach out to us for any questions at support@sourcefuse.com

With over 18 years of experience, Manpreet is the Chief Technology Officer at SourceFuse, leading the technology frat pack. Manpreet loves mentoring product teams! He passed out from Thapar University (Patiala) and BITS (Pilani).