Most applications use APIs to build the core of the application upon which the graphical interfaces are built. There are certain practices and standards to be followed for boosting the development quality and time. So this post will provide you the guidelines for REST APIs Best Practices
In the Introductory Post of Restful Web Services, we learned About REST APIs, like what is REST API, and why should we use REST in our APIs. In this post, we will know what are the best practices which we can implement in our API development.
This is a Two-Part Post-Series. If you haven’t read the Introductory post yet, please check that post first.
Part One: RESTful Web Services
Part Two: REST APIs Best Practices
Here is a checklist to create RESTful APIs which follow best standards and clean architecture
1. Version your API
Always use versions in your API like
domain/api/v1
For example, we have recreated or re-formatted our whole API, if any client is using our API in their application, then those changes may cause their application break, so to prevent these issues we should always use versions in our API.
Note: do not use decimal numbers in API versions like domain/api/v1.2
2. Handle Errors with HTTP Status Code
Imagine Your API without error messages. If something goes wrong, how will you be able to trace what went wrong?
So, it’s a good idea to handle each and every error with the relative Error Codes
3. Your URL should use a noun instead of verbs
Let’s understand this with an example
Check the wrong URL first (which is using verbs)
[GET] domain/api/v1/getMovieInformationByID/1
and now check with a noun
[GET] domain/api/v1/movies/1
So we can use noun URLs to easily understand the structure.
4. Do not use the GET method for changing the state
See the example below:
[GET] domain/api/v1/account/plan/1/subscribe
[GET] domain/api/v1/account/plan/1/unsubscribe
Always use the preferred method for a particular action.
Do not use the GET method for changing the state, because GET methods are only meant to fetch data, they should not perform any actions related to insertions or updates in the database.
5. Always Use Plural nouns in URLs
There is no Hard & Fast Rule defined for using the plural or singular noun in URL, but we should always use the plural noun because we fetch data in a collection.
So you should use:
Movies instead of a movie
Users instead of a user
6. Use Sub-URLs for relationship
The main benefits of using Sub-URLs for relationship is readability, This way we can improve the readability of our API URLs and we can easily know the relationship by checking the API URL only, see the example below to understand the Sub-URLs
[GET] domain/api/v1/movies/5/cast // Get casts for movie with an ID of 5
[GET] domain/api/v1/movies/5/reviews // Get reviews for movie with an ID of 5
What tools do we need to test APIs?
There are plenty of tools available on the internet, We love mainly two tools to test our APIs:
1. Postman is the most loveable and API Development Environment on the internet, they provide the best experience for testing/building and sharing your API.
2. Insomnia is another great tool, which we use for testing our APIs, It’s an easy to use tools, just download it and it is up and running.
Conclusion
Now we know what are the best practices for writing APIs and how we can implement REST principles while writing our APIs. Following these REST principles will boost your API development quality and time.
If you want to document the maturity of the APIs, you can do so by using the Richardson Maturity Model.
In case of any questions related to REST API, please ask us in the comments below.
