A Brief Guide to REST API Best Practices

In their infancy, APIs were developed using RPC technique (Remote Procedural Call). It seemed like the API was executing locally giving it a look of functions. However, this made it difficult for the programmers, especially when it was required to transfer it to the web. All because of the connection-less nature of HTTP protocol.

People did try to solve it by introducing modifications into RPC model. It indeed made the movement of apps to web faster. But the code turned out to be really inefficient. In the meantime W3C came up with REST and HTTP 1.1 creating ripples across the API landscape.



And since REST (or REpresentational State Transfer, as it is known in academic circles) came into picture, it has dominated the landscape of APIs.

Despite the popularity, REST is often not deployed in its best form. There’s a lot of ambiguity and diversity in understanding REST. That’s why we have come up with a brief guide to help you understand the REST API best practices.

Keep URLs simple and descriptive

The fundamental is to separate API into logical resources. And assign each of these resources a base URL.

This will make your API easy to understand and self-descriptive. Here’s a simple example:

Screenshot (2)

Instead of saying /jobs or /jobs-listing, this website uses /job/listing. This is a classic example of a separate resource and a unique URL for each of them.

For simplicity, some even advice using only 2 base URLs per resource.

Remove complexities under the string query

Most modern APIs come across functionalities of filtering based on some parameters which are associated to a resource. In these cases, one has to go beyond the resource level scope of the uniform resource.

For example, /api/jobs?intern=true&location=texas. This is how you will query for all interns available in Texas.

Typically when you request a resource on a RESTful API you will have nested resources that will come in the form of a reference.

Here’s one more example from It shows the kind of URL for the query of all Men’s new graphic tees for the caricature theme.

Screenshot (3)

Do NOT use GET for state changes

The primary and the most used methods in HTTP protocol are GET, PUT, DELETE, and POST. This is basically analogous to HTTP verbs for CRUD: Read, Create, Delete, and Update respectively. There are other verbs as well which are negligibly used.

However, the use of GET is avoided mostly by the developers when there is a change of states involved.

Use nouns and not verbs

Though it may sound strange, but there’s a logic behind this.

For any resource that you model, it would be foolish to consider an object in isolation. It is related and also interacting with all the other resources. Once you start using verbs, it will become difficult as the number of actions on the resource increases.

So to avoid the slippery slope, we resort to using nouns. Here’s chart to give you a better picture.

/t-shirt Returns a list of t-shirts Create a new ticket Update the t-shirts data in bulk Delete all t-shirts
/t-shrit/123 Returns a specific t-shirt Method not allowed (405) Update a specific t-shirt Deletes a specific t-shirt

Avoid using:




Use [relevant] HTTP status codes

Start by mapping the HTTP status codes to relevant standard-based codes.

With over 70 HTTP codes, it is difficult to memorize all of them. So choose status codes which are only relevant to your API. Sometimes developers end up choosing uncommon status codes leading to project delays and even distant from building a reliable, robust API.

Most API developers or companies use a very small subset of all HTTP codes. For example, the Google GData API uses only 10 status codes, Netflix uses 9, and Digg, only 8.

Handle Errors with HTTP Status Codes

Now that you have mapped relevant HTTP status codes with standard codes, you also need to add HTTP status codes for errors.

Along with appropriate HTTP status code, your API should also return a message in the response, a message for the developer, and a message for the end user.

Here are a few error codes should which will be sufficient for most purposes:








Always use HTTPS/TLS

It must be evident if you’re a developer reading this. No exceptions here unless you don’t care if a 3rd party monitors or modifies a request in transit from the client to you or from you to the client.

But with REST API, HTTPS does matters. Simply because it is extremely easy to access your API from anywhere in the world. And not all networks are secure: airports, public w-fi, airport, etc. All communications has to be secured by default. And having an SSL certificate is a simple way to ensure your information remains confidential.

To know more, see this YouTube video HTTPS Everywhere, a talk given by Ilya Grigorik and Pierre Far at Google I/O 2014.

Use URLs for API versioning

The most pragmatic way to manage API versions it to put the version number at the base of your URL. For example,

Versioning by URL allows developers to figure out which version of the service is in use at a glance. Just look at the HTTP request URL, and you know everything. /api/v1/ /api/v2/ and so forth.

You can also use the API version as a parameter ?version=v2 if you want to provide a different way to query different versions through the URL. Knowledge of the API can help with the creation of your app and improving the security of the app.

Contact Snyxius