Credit: This post is based on Roy Fielding’s dissertation. His work describes the REST architecture in detail, and it is a useful read I highly recommend.
So, What is a RESTful API?
Some will say:
“It is an API that utilises HTTP requests to
GET, PUT, POST and DELETE data.”
Many will also say:
“It’s about identifying resources with URIs”
Others will also shout at you:
“You forgot the links, it must use hyperlinks!”
At the end, one may just concludes:
“Basically, it’s just an API that uses HTTP properly!”
Some of these statements are wrong,
Some are partially true,
but it does not matter,
because they are all missing the point.
In order to be able to design a RESTful API,
First, we must understand REST!
What REST is NOT?
REST is:
- Definitely not HTTP
- Not a protocol
- Not a specification
This is why there are many confusions and debates around REST APIs.
What is REST?
REST is architectural style.
Oh, ok… but what is an architectural style?
Architectural Style
It is really just the architecture, plus a set of constraints applied on the architecture producing the desired architecture.
By applying these constraints, we end up with a desired architecture which is optimised for the common use cases.
REST stands for Representational State Transfer
It was written down by Roy Fielding in his PHD dissertation in year 2000, where he described the existing and modern Web architecture as an abstraction.
The name “Representational State Transfer” was intended to evoke an image of how a well-designed web application behaves.
Roy described REST with a simple example:
Let’s consider a network of web pages as a virtual state-machine.
Each page represents a state:
- First, the user receives first state as index state.
2. Then the user progresses through the application by selecting a link (here the about page link)
3. Resulting the next state being transferred to the user.
The transferred about page now represents the current state of the application.
REST is still not HTTP
Of course, back in 2000, the web was already running on HTTP, and Roy with his fellow engineers were working hard improving it.
However, REST does not define the specific details of a system implementation nor does it define any protocol syntax.
It is entirely possible to have a RESTful architecture over non-HTTP protocols.
For example, CoAP (Constrained Application Protocol) is a RESTful protocol for embedded devices (the Internet of Things) and was designed to use minimal resources both on device and network.
So why use REST?
The World Wide Web is based on REST architecture.
Therefore, if you build a non-RESTful API to be used on the web, then you will end up with a sub-optimal system.
Sub-optimal in relation to the optimised architecture.
This is important to mention because a non RESTful API can be sub-optimal in the network architecture but optimal for other concerns. For example, modern front-end applications can have very specific needs hence the growing number of data fetching libraries such as GraphQL or Falcor.
So when is an API RESTful?
An API is RESTful when it is acting under the REST constraints at all times.
REST defines 6 constraints to achieve the desired system optimisation:
1. Client-Server
This constraint is based on the separation of concerns principle.
This allows components to evolve independently. When building our API, it is acting as a server servicing many number of clients.
2. Stateless
Communication between client and server must be stateless. This means that each request from client to server must contain all the necessary information to complete the transaction.
The main advantage of this constraint is that the system is able to scale better because the server does not have to store client state between requests. Not having to remember client state information frees up server resources so it can serve more clients simultaneously.
3. Cache
The most efficient network request is one that does not use the network.
When we build our API, it must not ignore caching.
4. Uniform Interface
In order have efficient caching in a network, components must be able to communicate via a uniform interface. With a uniform interface, payload can be transferred in a standard form.
4.1. Identification of Resources
This means that any information that can be named can be a resource (image, document, a concept like a person or even a collection of other resources)
4.2. Manipulation of resources through representations
A resource can be represented in many different ways.
For example as HTML, XML, JSON or even as a JPEG file.
This rule means that clients interact with resources via their representations which is a powerful way to keep resource concepts abstracted from their interactions.
4.3 Third, self-descriptive messages
This means that a resource can be described in a request message as well as the server can respond with descriptive state messages. Yes, HTTP headers and response codes are good implementations for this rule.
4.4 Hypermedia must be the engine of the application state
This really just means that the application should be driven by links, allowing clients to discover resources via hyperlinks.
As you can see many of these rules can be found implemented in the HTTP protocol. So when an API is using HTTP properly, it is a huge step closer to being RESTful.
5. Layered System
In a layered system, intermediaries, such as proxies can be placed between client and server utilising the web’s uniform interface.
One of the advantage of a layered system is that intermediaries can then intercept client-server traffic for a specific purposes; for example caching.
6. Code On Demand
This is an optional constraint and it allows clients to download programs for client-side execution. Best example for this is front-end JavaScript applications. This may sound very obvious to us now, but in the early ages of the Internet it was an evolving concept and it is a useful part of the Internet architecture.
So how to build a RESTful API?
Use HTTP properly
If you are building a RESTful API use a RESTful protocol. For the web, HTTP protocol is a given choice. Build your API so it is utilising HTTP in the right way.
Build a uniform interface
Map your concepts to resources and assign the appropriate identifiers to each one of them. A simple example would be a user database service. In such a service we can name two resources; user and users (collection resource). These resources could be identified with the /users and /user/{id} URIs in your API interface.
Drive your API with hyperlinks
Use links to connect your resources. This will make your API discoverable for clients that have very little initial knowledge about your resources.
Be aware of the REST architecture
For me, the main take away from building a RESTful API is that how important it is to understand the Internet and its underlying architecture.
An architecture, that is optimised for the common use cases. We can either take advantage of this optimisation or we can choose to ignore it.
It is really up to us developers.
Thank you for reading my post.
Feedback and thoughts are always welcome in the comments section.
