Rest Api Design Principles/Best Practices
We all might know REST stands for Representational State Transfer, which is nothing but a Software Architectural Style which is some set of rules to create web services. RESTful services have mainly designed for loosely coupled systems over HTTP.
Let’s see some of the best practices that we can follow to design REST API for any client…
Consistency
As the name suggests similar endpoints should behave in a similar way. Ideally, someone looking into your API should be able to make a guess on what the purpose of your API is.
It’s always better to synonymize a resource with a web page.
Do not make one resource too large, this will only lead to loss of bandwidth. We should always try to make a resource in such a way that it fulfills one responsibility.
Once a developer becomes familiar with one of your APIs, he should be able to follow a similar approach for other APIs.
Make it STATELESS
You should not store data on your servers, where you running your web services. Make it loosely coupled with the underlying infrastructure.
If you need to develop a stateful service (eg. sessions, request/response metadata, etc), store it in databases.
Use Proper HTTP Method
This point can be compared with point 1, but I wanted to be specific about this particular point.
We know there are many HTTP Methods available eg. GET, HEAD, POST, PUT, PATCH, DELETE, CONNECT, OPTIONS and TRACE, but we should know there use cases properly before designing REST APIs.
Once you have your resources defined, you need to identify what actions apply to them and how those would map to your API. RESTful principles provide strategies to handle CRUD actions using HTTP methods mapped as follows:
- GET /books — Retrieves a list of books
- GET /books/232— Retrieves a specific book
- POST /books — Creates a new book
- PUT /books/11 — Updates a book
- PATCH /books/789 — Partially updates ticket #12
- DELETE /books/1135 — Deletes a book
The great thing about REST is that you’re leveraging existing HTTP methods to implement significant functionality on just a single /books endpoint. There is no method naming conventions to follow and the URL structure is clean & clear.
Use Cache
Proper use of caching can speed up the request/response cycle to a large extend. There many strategies to use caching on the server-side. We will talk about it in some other post.
An example can be, storing book details with book_id 232 in an in-memory store so that any request trying to fetch that particular book can get it quickly without hitting persistent storage.
Layered system
A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. If a proxy or load balancer is placed between the client and server, it won’t affect their communications and there won’t be a need to update the client or server code
You can scale your servers by using Load Balancers and by providing Shared Caches.
Versioning
Always version your API. Versioning helps you iterate faster and prevents invalid requests from hitting updated endpoints. It also helps smooth over any major API version transitions as you can continue to offer old API versions for a period of time.
There are mixed opinions around whether an API version should be included in the URL or in a header. Academically speaking, it should probably be in a header. However, the version needs to be in the URL to ensure browser explorability of the resources across versions (remember the API requirements specified at the top of this post?) and to have a simpler developer experience.
Above can be some important points to consider before designing your RESTful APIs, but there can be other best practices which you may want to use in your production system…
- Use SSL for all your endpoints
- Document your APIs
- Use GZIP compression
- Use JSON only format for response
- Use proper HTTP status code. Eg PageNotFount->404, BadRequest->400, etc
There are many more to discuss but I leave that to you…
Please comment if you think I have missed any such important points.
Happy Coding…
