Writing beautiful REST Apis

Most modern web applications use a common practice of leveraging REST API to make a seperation between data pane and control pane. The API acts as the control pane which is not data intensive but controls the behaviour of application while the static application acts as simple data pane. This seperation makes it possible to extensively cache the user-interface of application for faster response and providing a better user experience. In this article i will be discussing some common practices i have learnt over the years to make an API that is simple to use and yet easy to manage as the size of project grows.


1. Embrace stateless authentication

This goes without saying but REST APIs need a stateless authentication mechanism. Stateless authentication put in laymens terms is the session data not being stored on server. That means if the client request hits another node of the server it would respond in the same way. The best method i have always prefered for a long time is using Json-web-token which makes it possible to embed user data right inside the token variable and reduces a database lookup query to get user metadata.

One thing to remember here is because there is no user session data stored on server it is a good idea to have an expiry time for token. The expiry time can vary according to application needs. A little extra work is required in this case to write route to generate a new token based on previous token and refresh token.

So in order to sum this up, you would need to implement two routes. One for login and other for refresh. Login route returns token and refresh token. On expiry the token and refresh token can be sent back to server in exchange for new token

2. Seperate api response meta and data

While sending json response from api i always found out that there is some meta data that i cannot pass with standard reponse, like the error Code or status Code . It’s a good practice to differentiate between them. More example of meta content includes the api call limit or simply the expiry time for content.

3. Use proper HTTP verbs

If you have ever written a REST API, you would get the purpose of this step. But if you have not, there are 4 most common http verbs that are used while designing an api

GET Use to simply get a resource from server.

POST Use to add new resource to server.

PUT Use to update resource on server.

DELETE Delete a resource from server.

Most people should be familiar with GET and POST . Now the next time you are thinking about writing code to update or delete a resource use proper verbs associated with those.

Note that DELETE method does not take any body content. You will have to pass resource description in URI for api itself.

4. Use of proper status codes

There are a lot of important status codes all with different meanings. The list below should help you use the right response for right query.

200 OK : Use during a simple GET request. Either fetching a list of resources or a specific resource object.

201 CREATED : Use after a POST request when a new resource is created.

204 NO CONTENT : Use after DELETE request when a resource no longer exists.

400 INVALID REQUEST : The parameters passed over to server are incorrect and server can do nothing to make it right.

401 UNAUTHORIZED : Use the status code in case authentication is required to access the resource requested. This can be used with all the verbs.

403 FORBIDDEN : Use this if the user is authenticated but does not have the permissions to the requested resource.

404 NOT FOUND : Use this response in case the resource does not exist on the server.

500 INTERNAL SERVER ERROR : The most common case for this response is when server hits an exception.

5. API Version

Adding an api version in headers is very important and makes sure that client does not break with changes on api. The same can simply be added using HTTP Header X-API-VERSION.

6. Paginate your API

Getting a list of resources from server might be a huge time consuming task and affects the performance of api. Make sure you are adding support for pagination. The details of the same can easily be added in meta section of response for client.

7. Use cache to enhance API performance

Just like the way you would cache a view remember to cache resource objects also to offload your database servers. I personally prefer using redis but there are a lot of other options out there.