RESTful API Designing — The Best Practices
In this article, we will look at the best practices of restful api design. It has been prepared assuming that you have knowledge about the subject. I tried to explain the subject without going into too much detail.
There is no one right way to design an API. We should think of API as an interface. So when the developer interacts with the api it should be easy to understand and easy to use. Developers’ experience is the best metric in this regard.
API endpoint
Let’s write few APIs for Garage which has some Car, to understand more.
- The URL should only contain resources(nouns) not actions or verbs.
- This is where the HTTP methods (GET, POST, DELETE, PUT), also called as verbs, play the role.
- The resource should always be plural in the API endpoint and if we want to access one instance of the resource, we should always pass the id in the URL.
Other use cases would be if a resource has resources under it, e.g. Garage of a Car, then a few sample API endpoints would be as follows:
- PUT / garages/3 should update garage 3
- GET /garages/3/cars should get the list of all cars from garage 3
- GET /garages/3/cars/45 should get the details of car 45, which belongs to garage 3
- DELETE /garages/3/cars/45 should delete car 45, which belongs to garage 3
- POST /garages should create a new garage and return the details of the new garage created
Conclusion: The paths should contain the plural form of resources and the HTTP method should define the kind of action to be performed on the resource.
HTTP methods
HTTP has defined sets of methods that indicate the type of action to be performed on the resources.
- GET method requests data from the resource and should not produce any side effect.
- POST method requests the server to create a resource in the database, mostly when a web form is submitted.
- PUT method requests the server to update resource or create the resource, if it doesn’t exist.
- DELETE method requests that the resources, or its instance, should be removed from the database.
HTTP response status codes
When you’re talking to an API, the server sends back an HTTP code to signal the status of your request.
The important status codes:
200s Successful responses
E.g: 200 Ok The standard HTTP response representing success for GET, PUT or POST.300s Redirects
E.g: 304 Not Modified indicates that the client has the response already in its cache. And hence there is no need to transfer the same data again.400s Client errors
E.g: 400 Bad Request indicates that the request by the client was not processed, as the server could not understand what the client is asking for.500s Server errors
E.g: 500 Internal Server Error indicates that the request is valid, but the server is totally confused and the server is asked to serve some unexpected condition.
Searching, sorting, filtering and pagination
Searching, sorting, filtering and pagination are all actions that can be performed on the collection of a API. This lets it only retrieve, sort, and arrange the necessary data into pages so the server doesn’t get overloaded with requests.
Sorting:
Allows sorting ascendingly and descendingly by field.
GET vehicle-damage-inquiry?sort=id,descFiltering:
For filtering the dataset, we can pass various options through query params.
GET vehicle-damage-inquiry?userId={{}}&chassisOrPlate={{}}Pagination:
Instead of pulling data as one piece we can pull the data piece by piece by specifying size and offset.
GET vehicle-damage-inquiry?userId={{}}&chassisOrPlate={{}}&page= {{}}&size={{}}Versioning
Used when designing an API to inform clients in order to not break the existing products or services and force clients to use newest version.
GET http://api.carservice.com/v1/brand-new-car/cidWe are using the url for the API versioning starting with the letter „v“ if you make changes that is incompatible with the older version, you should increment the number near “v”, e.g. v2 or v1.x.x.
GET http://api.carservice.com/v1.1.2/brand-new-car/cidDocumentation
When you make a API, you need to help clients learn and figure out how to use it correctly. The best way to do this is by providing good documentation for the API.
One of the most common tools you can use for API documentation is Swagger.
Conclusion
While designing API, I tried to share the most needed information with you. Some of the content in my article is from my own experience, some of it is taken from other sources.
Thank you for reading…
