Servage Magazine

Information about YOUR hosting company – where we give you a clear picture of what we think and do!

Best practices for designing a REST API

Saturday, October 22nd, 2016 by Servage

restThanks to things like the Internet of Things, Application Programming Interfaces (APIs) have become a big part of the internet. In addition to this, many applications allow other applications to integrate with them. Both of these features often happen using an API. Understanding how APIs work, and even better, understanding how to design them, is a valuable skill. So, what makes a good REST API?

Resource names

One of the first questions that comes to your mind when designing an API is probably this: What should a URI look like? A URI is the address to a resource, such as a user account. A URI might look like this: “/users/1/products/2”. Should these resources be singular or plural?

This has been a controversial topic for a long time. Both forms are seen commonly, but it is generally more acceptable to use plural names for all resources.

HTTP methods

It might seem tempting to delete a user using the following GET request: “/users/1/delete”. However, you should always use HTTP methods meant for that type of request. This way you don’t have to set up too many redundant URIs. You can simply call the same resource name with a different method, and the action will be different for each type of method.

GET requests should be used for ready-only queries, in other words, for getting data. POST requests should be used to create a new resource. PUT is the right method to use for updating an existing resource. If you only want to update a small portion of a resource, such as an email address, use PATCH instead. To delete a resource, use DELETE.

There are more HTTP methods available, but there are the most common ones you will likely implement in your API.

API keys

An API key should never be stored in the URI. URIs are public and can be shared. API keys are like passwords and thus should never be shared. It is good practice to send an API using HTTP headers, more specifically the authorization header. Here is an example authorization header where “foobar” is the API key: “Authorization: Basic foobar”. Keep in mind that all APIs implementing this type of authorization should use HTTPS to prevent the API key from being sent in plaintext.

Versioning an API

Sometimes it is necessary to make major, backward-incompatible changes to your API. When you do so, existing API clients will fail to communicate with your API unless you version your API correctly. Chances are that you have seen APIs being versioned using URIs, such as “/api/v1/users/1”. While this works, it is not the best option. URIs should only contain information about the resource itself. So, how can API clients tell what version of the API they should use? The answer is again the HTTP headers. In the following example, a client wants to connect to the version 2 of the API: “Accept: application/vnd.example-com-v2+json”.

Best practices for designing a REST API, 5.0 out of 5 based on 4 ratings
Categories: Guides & Tutorials, Tips & Tricks


You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

No comments yet (leave a comment)

You are welcome to initiate a conversation about this blog entry.

Leave a comment

You must be logged in to post a comment.