REST APIs Best Practices

Anish Ojha ·

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 follows 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 noun 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.

Post Author Profile Image

Anish Ojha

For the past 8 years, he has been engaging with clients and potential clients to enable business transformation. He is committed to building a reputation for quality and delivery for our clients while building a strong technical and social culture within the company.

All posts by Anish Ojha

Add Comment

Your email address will not be published. Required fields are marked *