In this article, I am going to talk about how to design your RESTful APIs better to avoid common mistakes
Originally published by Tanmay Deshpande at https://medium.com
As software developers, most of us use or build REST APIs in day to day life. APIs are the default means of communication between the systems. Amazon is the best example of how APIs can be efficiently used for communication.
Some of you might have been already aware of Jeff Bezos’ mandate to the developers in Amazon. If you never got a chance to hear about it, the following points are the crux of it.
Eventually, this turned out to be the key to Amazon’s success. Amazon could build scalable systems and later could also offer those as services like Amazon Web Services.
Now let’s understand the principles we should follow while designing the RESTful APIs.
Keep it simple
We need to make sure that the base URL of the API is simple. For example, if we want to design APIs for products, it should be designed like:
The first API is to get all products and the second one is to get a specific product.
Use nouns and not the verbs
A lot of developers make this mistake. They generally forget that we have HTTP methods with us to describe the APIs better and end up using verbs in the API URLs. For instance, API to get all products should be:
and not as shown below
Some common URL patterns, I have seen so far.
Use of the right HTTP methods
RESTful APIs have various methods to indicate the type of operation we are going to perform with this API.
We need to make sure we use the right HTTP method for a given operation.
This topic is a bit debatable. Some people like to keep the resource URL with plural names while others like to keep it singular. For instance —
I like to keep it plural since it avoids confusion about whether we are talking about getting a single resource or a collection. It also avoids adding additional things like attaching all to the base URL e.g.
Some people might not like this but my only suggestion is to keep it uniform across the project.
Sometimes we need to have an API which should be telling more story than just by id. Here we should make use of query parameters to design the API.
/products?name=’ABC’should be preferred over
/products?type=’xyz’should be preferred over
This way you can avoid long URLs with simplicity in design.
Use proper HTTP codes
We have plenty of HTTP codes. Most of us only end up using two — 200 and 500! This is certainly not good practice. Following are some commonly used HTTP codes.
Versioning of APIs is very important. Many different companies use versions in different ways. Some use versions as dates while some use versions as query parameters. I generally like to keep it prefixed to the resource. For instance:
I would also like to avoid using
/v1.2/products, as it implies the API would be frequently changing. Also, dots (.) might not be easily visible in the URLs. So keep it simple.
It is always good practice to keep backward compatibility so that if you change the API version, consumers get enough time to move to the next version.
Use of pagination is a must when you expose an API which might return huge data, and if proper load balancing is not done, the consumer might end up bringing down the service. We need to always keep in mind that the API design should be full proof and fool proof.
offset is recommended here. For example,
/products?limit=25&offset=50. It is also advised to keep a default limit and default offset.
It is also important to choose how your API responds. Most of the modern day applications should return JSON responses, unless you have a legacy app which still needs to get an XML response.
Use proper error messages
It is always good practice to keep a set of error messages the application sends and respond to that with proper id. For example, if you use Facebook graph APIs, in case of errors, it returns a message like this:
"message": "(#803) Some of the aliases you requested do not exist: products",
I have also seen some examples in which people return a URL with an error message, which tells you more about the error message and how to handle it as well.
Use of OpenAPI specifications
In order to keep all teams in your company abide by certain principles, use of OpenAPI specification can be useful. OpenAPI allows you to design your APIs first and share that with the consumers in an easier manner.
It is quite evident that if you want to communicate better, APIs are the way to go. But if they are designed badly then it might increase confusion. So put your best effort in designing well, and the rest is just the implementation.
Thanks for reading ❤
If you liked this post, share it with all of your programming buddies!
What is REST? The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used
ＬＩＫＥ | ＣＯＭＭＥＮＴ | ＳＨＡＲＥ | ＳＵＢＳＣＲＩＢＥ In this tutorial, I will discussed about how to consume Web API Get method and display records in the ASP.NET View. Here, ...
ＬＩＫＥ | ＣＯＭＭＥＮＴ | ＳＨＡＲＥ | ＳＵＢＳＣＲＩＢＥ In this tutorial, I will discussed about How to Consume Web API Get method in ASP NET MVC. Blog : http://aspdotnetexplorer...
ＬＩＫＥ | ＣＯＭＭＥＮＴ | ＳＨＡＲＥ | ＳＵＢＳＣＲＩＢＥ In this tutorial, we learned how to consume Web API Get and Post methods in the ASP.NET View. Here, we will see how to con...
ＬＩＫＥ | ＣＯＭＭＥＮＴ | ＳＨＡＲＥ | ＳＵＢＳＣＲＩＢＥ In this tutorial, we learned how to consume Web API Get,Post and PUT methods in the ASP.NET View. Here, we will see how to...