You're probably not RESTing correctly

When people talk about designing an API, they'll inevitably talk about REST, or Representational state transfer. After the API is finished, they may claim that their API is 'RESTful'; but what does that actually mean? And is it really RESTful?

As happens often in technology, as soon as a term becomes 'trendy', people just attaches it to everything, and more often than not, this is done incorrectly.

So before continuing in this article, I'd like you to keep a few things in mind:

  • REST is an architectural style, it's the manner / rules / patterns in which you construct your API. You can describe an API as 'RESTful' if it conforms to that style.
  • Not all APIs are RESTful. Many who claims to be RESTful in fact aren't.
  • REST is really nothing new, you are probably well attuned to it already because it's how the World Wide Web is structured, so don't let the terminology alienate you.

What is REST?

REST is an architectural style - a set of rules / constraints which if your API conforms to, you can call your API RESTful. Not all APIs have to be RESTful to be 'good'.

The REST architectural style is defined by the following constraints - Client-Server, Stateless, Cacheable, Layered system, Code on demand (optional) and Uniform interface. Just reading these terms isn't particularly helpful, so let's dive in and examine each one individually.


This constraints requires a separation of concerns (SoC) between the client and the server. This means the client should perform some roles (or concerns), and the server performs other roles.

For example, the server is responsible for data storage, while the client is responsible for the user interface. In this example, the client would query the server for data, and use that data to decide what to display on the screen.

When talking about APIs, this means that

  • the same API can be used by many clients
  • The server- and client-side code can be developed independently

If a response is going to be the same given the same request, then that response should be cached to increase performance because:

  • A significant portion of the time taken between request and response can be due to the transfer time of the messages between client, intermediate proxies and the server. If the response is already cached in the intermediate proxies, then this time is reduced, and the perceived performance is higher for the client.
  • If the request must be processed each time by the server, it would take up unnecessary resources.

So a RESTful architecture would require that the response message must include an indication of whether it should be cached, and, if so, for how long.

Layered system
Code on demand (optional)

This is an optional constraint of the REST architecture which means it is not necessary to fulfil this in order to call your system RESTful.

Uniform Interface

An interface is a "shared boundary across which two separate components of a computer system exchange information"

Identification of resources

So remember, from above, about the Client-Server Separation of Concerns constraint? In most cases, this means that data is stored on the server, and there needs to be way for the client to access that data.

We call a unit of data a resource, and there must be a way to identify that resource; with HTTP, this is done through a Uniform Resource Locator (URL).

For example, let's assume we have a products database, and the client wishes to access the product with the id of 576. The server can exposes a route such as and that would identify that resource.

However, a resource can be represented in different formats - XML, JSON, HTML etc. These we call a resource's representation. The representation that the server sends back depends on the representation that the client is willing to accept. This is usually determined by the request message's Accept header.

Manipulation of resources through these representations
Self-descriptive messages

The response from the server should be self-descriptive, which means it has all the information to allow the client and intermediate proxies to know how to process it correctly. This involves setting a cache header, specifying the Media Type (or MIME) so the client can invoke the corresponding parser.

Hypermedia as the engine of application state (HATEOAS)

This is a big term but it's really quite simple. The response that the server sends back to the client should contain all the actions that the client can take.


REST is designed to give a more performant and maintainable architecture.

How (not) to Implement REST properly?

In the remaining sections, we will be talking about implementing REST over HTTP because that's the most common use case. Note that, however, REST is not bound to a particular protocol.

Make a pretty URL, and leave it

URL stands for 'Uniform Resource Locator', which means each unique URL should locate a particular resource.

For simplicity sake, let's say you have a user table/collection in your database, and you want to expose an API endpoint for developers to access information about a particular user.

(( What the REST client should do is to send a request to a URL identifying the resource (a user), and by using a HTTP verb (GET, POST, PUT, DELETE) inform the REST API provider / receiver what action the client wishes to perform on this resource.

In the request, the REST client should also specify, using the Accept header, the content type that it will accept back as a response from the REST API provider.

Misconception! There is nothing as a 'RESTful URL'. This is probably the most common misconception about REST, and it is not helped by API providers using the wrong terminology.

Instagram has, on its API documentation, stated that "We do our best to have all our URLs be RESTful." But in fact, that's inaccurate.

While a URL such as /user/24/update/ suggests that it is not pointing to a resource but an action/verb, it may very well mean a resource - the last update for the user. So there is no RESTful URL.


Advantages and Disadvantages of REST

REST is so trendy that most people just assume it's the best and every API needs to be RESTful. But you should appreciate that there's never a tool that fits every situation; The decision over which architectural style (and it is only a style, not a requirement) to use should be made after considering the audience which is using your API,

URL is King


Read More