The last time Hackerfall tried to access this page, it returned a not found error. A cached version of the page is below, or clickhereto continue anyway

REST best practices

REST APIs are a very common topic nowaday; they are part of almost every web application. A simple, consistent and pragmatic interface is a mandatory thing; it will be much easier for others to use your API. Even if these practices may look common to your eye, I often see people that don't really respect them. That's why I decided to write a post about it.

Here are some best practices to keep in mind while designing a RESTful API.

Disclamer: these best practices are what I think is good, based from my past expriences. If you think otherwise, feel free to send me an email so we can have a discussion about it.

Version your API

API versions should be mandatory. This way, you will be futureproof as the API changes through time. One way is to do is to pass the API version in the URL (/api/v1/...).

One other neat trick is to use the Accept HTTP header to pass the verison desired. Github does that.

Using versions will allow you to change the API structure without breaking compatibility with older clients.

Use nouns, not verbs

One thing I often see is people using verbs instead of nouns in their resources name. Here are some bad examples :

For a clean and conscice structure, you should always use nouns. Moreover, a good use of HTTP methods will allow you to remove actions from your resources names.

It is much cleaner that way.

Use the plural form

In my opinion, it is not a really good idea to mix singular and plural forms in a single resource naming; it can quickly become confusing and non consistent.

Use /artists instead of /artist, even for the show/delete/update actions

GET and HEAD calls should always be safe

RFC2616 cleary states that HEAD and GET methods should always be safe to call (in other words, the state should not be altered).

Here is a bad example: GET /deleteProduct?id=1

Imagine a search engine indexing that page...

Use nested resources

If you want to get a sub collection (collection of an other one), use nested routing for a cleaner design. For instance, if you want to get a list of all albums of a particular artist, you would want to use GET /artists/8/albums.


Returning a very large resultset over HTTP is not a very good idea neither. You will eventually run into performance issues as serializing a large JSON may quickly become expensive.

An option to get around that would be to paginate your results. Facebook, Twitter, Github, etc. does that. It is much more efficient to make more calls that takes little time to complete, than a big one that is very slow to execute.

Also, if you are using pagination, one good way to indicate the next and previous pages links is through the Link HTTP header. Github does that too.

Use proper HTTP status codes

Always use proper HTTP status codes when returning content (for both successful and error requests). Here a quick list of non common codes that you may want to use in your application.

Success codes
Client error codes

A more complete list of status codes can be found in RFC2616.

Always return a consistent error payload

When an exception is raised, you should always return a consistent payload describing the error. This way, it will be easier for other to parse the error message (the structure will always be the same, whatever the error is).

Here one I often use in my web applications. It is clear, simple and self descriptive.

HTTP/1.1 401 Unauthorized
    "status": "Unauthorized",
    "message": "No access token provided.",
    "request_id": "594600f4-7eec-47ca-8012-02e7b89859ce"

Continue reading on