9 Best Practices for REST API Design

Harsh Patel
Nov 12, 2020 · 6 min read
Image for post
Image for post

On many occasions, we don’t value the importance of establishing a clean, understandable, and scalable architecture when developing a REST API (or attempting to have this pattern), but in the long run, this has a giant impact as the application grows.

Suppose that the time has come to expose the interface that we were developing to users, how sure are you that they understand the same thing that you try to transmit in your interface? Not only is the understanding of the users who consume the application relevant, but also that it is understandable for your team and future people who will come to work with the application. It is essential to establish from the beginning of an architecture that everyone will respect.

These are several of the aspects that I consider of most importance to take into consideration:

1. Use HTTP methods to give your endpoints meaning

REST API encourages us to use an for each of the application’s CRUD actions. Among them, we have the following variety: GET, POST, PUT, DELETE, and PATCH. The name of the endpoint associated with the resource must be accompanied by the HTTP method related to the applied action.

- GET /get_cats
- POST /insert_cats
- PUT /modify_cats
- DELETE /delete_cats
+ GET /cats
+ POST /cats
+ PUT /cats
+ DELETE /cats

2. Status codes must be according to the result of our API.

One of the most important qualities of our application is that the return of our endpoints is related to the corresponding status code. This means that the moment our result is successful or unsuccessful, we can relate in a more descriptive way the message we want to convey.

For example, if we get a status 200, we can immediately know that our result is successful, otherwise, if we get a status 400, the result is failed.

It is important to know the existing and know which case we need to apply each one of them, since it may happen (and it’s very common) that the return message is incorrectly associated with some status code, which is extremely harmful for the application since it generates confusion for developers and consumer users of our REST API.

// Bad, we return status code 200 (Success)
// associated with an error object
"status": 200,
"error": {...}
// Good
"status": 200,
"data": [...]

3. Filter, sort, and pagination support

Many cases in any application that consumes our API, will want, in some way, to consume fewer resources from our service, either due to performance, a search system, the information is excessive, or as simple as showing something particular from our resources.

Filter, sort, and pagination, in addition to expanding the functionalities of our API, helps us reduce the consumption of resources on our server.

Let’s imagine the case of an endpoint that returns millions of results, how would our server react? (He would surely cry and collapse 😜).

  • GET /cats?race=misumisu&age=1 -> Filtering, retrieve all the cats that have the following properties: race is misumisu and the age is 1.
  • GET /cats?limit=15&offset=0 -> Pagination, return 15 rows starting with the 0 row.
  • GET /cats?sort=descending -> Sort, return rows sorted by name in ascendant.

4. Plural endpoints

One of the daily discussions that I come across regarding various API developments is deciding whether to use singular or plural for the construction of endpoints. In short, we want to maintain a solid consistency in our application, and for this, my recommendation is to build the endpoints in plural.

Resources will not always have a single result, a table can have many results and even if it had only one, and we place it singular, we will not maintain consistency in the format of the name of our routes.

“Consistency is the key to success” 🔑

- GET /cat
- GET /cat/:id
+ GET /cats
+ GET /cats/:id

5. Name endpoints with the name of your resources

Speaking of consistency, if we know that a route is responsible for handling the actions on a resource, it is essential to name it with the name of the resource directly, so when a person consumes our API, they will understand which entities they are working on.

For example, if you are going to return cats, you are not going to call your endpoint /dogs 🐶.

6. Resource hierarchy

What if we want to access a closely linked entity that belongs to a resource?

To show this relationship we have two options:

  • Hierarchically append article in our author endpoint
  • Query string

Let’s take the classic example of “author” and “articles”.

GET /authors/betoyanes/articles/create_cat_memes
GET /articles?author=betoyanes&name=create_cat_memes

These ways are valid and I have seen them in many projects. Personally, I consider it cleaner to use a query string than expanding the current path. The more the application scales, we will surely have a greater hierarchy and in turn, the route will expand. Even so, it is according to the criteria of each person, so use the one you prefer the most!

7. Versioning

As we develop, it is inevitable to have a stable and definitive version of our API, without errors, and bulletproof. Let’s imagine we deploy our API and several clients are starting to use it, what would happen at some point when you need to add or remove more data from a resource? Possibly you generate a bug on the external services that consume our interface. That is why it is essential to have a versioning mechanism for our application.

There are several ways, but I am a fan of the versioned URI, in which we will explicitly have the version of our route in our endpoint.

// URI versioning v[x] syntax
GET /v1/cats
GET /v2/dogs

8. Caching

One of the powerful tools that will enhance an API in speed and low resource consumption is caching, the idea is not to ask your database for the same request multiple times if it continues to have the same result. There are several services that can help us implement this system, among them, one of my favorites is .

We have surely heard that implementing a cached functionality generally comes with costs, and this is not the exception. Let us ask the following questions, is the information dynamic or is it static? If it’s dynamic, how often does the information change?

🚨 It is important to be aware of having long periods of information in cache, this can cause false results of the API by keeping the information for a long time, it is recommended to have short periods of the cache.

9. Documentation

One of our best weapons and most hated by many people is documentation. In this context, a documented API is essential so that our users who consume it can understand several important aspects of our interface, including accessibility, responses, requests, examples.

  • Accessibility: The location and access of the interface are one of the most important qualities, and we do not want to give a how_to_use.txt to customers. Exposing our documentation on the cloud where everyone can see it, is the most convenient thing we can do.
  • Responses and Requests: The information we provide has to contemplate all the possible results that any resource may produce and how to consume them.
  • Examples: It is very important to provide examples of how we can consume our interface, even if it is a bash script that we can execute in the console and get a response from it.


Remember that our API is the interface that we expose to consume our back end service, with this in mind, it is important to apply the best possible principles so that the people who consume and work on it, are to their liking.

Although we are developing a personal project, we need to try applying the best principles that we consider, so we can get practice for when we enter a development team or project 💪.

I hope this article has helped you and adds some principles to your collection of good practices for your REST API! Do you have any other principles to add? Let us know in the comments section! 💬

If you like this article then you should also like another part:

If you love this article help me to buy a coffee:

By Harsh Patel ( )

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Sign up for 💌 Weekly Newsletter

By Weekly Webtips

Get the latest news on the world of web technologies with a series of tutorial 

By signing up, you will create a Medium account if you don’t already have one. Review our for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Harsh Patel

Written by

🤠 Internet Cowboy | 💻 JS Aficionado | http://imharshpatel.com/

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Harsh Patel

Written by

🤠 Internet Cowboy | 💻 JS Aficionado | http://imharshpatel.com/

Weekly Webtips

Explore the world of web technologies through a series of tutorials

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface.

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox.

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic.

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store