REST is one of the most important concepts in today's web-centric development circles. You've probably heard about it even if your main focus isn't web development. Despite its popularity, there's a lot of confusion about what it really is. Let's take a look at some concepts to better understand what it means to be RESTful.
It all starts with a guy named Roy
The term REST originates from Roy Fielding's doctoral dissertation, Architectural Styles and the Design of Network-based Software Architectures. It is, in essence, an architectural style for distributed hypermedia systems whose main goal is interoperability between web services.
A group of constraints define the architecture and dictates guidelines on how web services should interact with each other. A system is RESTful as long as it abides by all these constraints. The most important aspect of REST is that it doesn't tell you how to implement your components or which protocol to use. All the principles are about the interaction between components and the interpretation of data exchanged.
In REST, the Resource is the main information abstraction
Resources represent things like people, buildings, the value of stocks at a given time, and also collections of these things. In other words, resources are anything you can put a name on.
Because you need a way to identify a particular resource (often for retrieval), they have resource identifiers. Most modern implementations use URLs for this task. For example, a way of getting a specific apple resource could be http://myapiexample/apples/{apple-resource-id}.
A resource's representation is another important concept. Representations consist of the data for describing a resource plus its associated metadata. These representations can take the form of images or HTML documents, or also JSON or XML. Do not to confuse a resource with its representation: you can represent the same resource as either HTML or JSON. This decoupling between a resource and its representation enables you to access them in a huge variety of formats.
The 6 architectural constraints
There are six architectural constraints that define what a REST system should look like. Their goal is to provide a consistent way to structure a system and at the same time protecting developer creativity. Because of this, the constraints are guiding principles that leave implementation details up to the engineer.
1. Client-server
In the first place, the system must adhere to a server-client architecture. The main benefit is the separation of concerns, letting user interface and data storage evolve independently of each other. Furthermore, the user interface becomes more portable as clients only need to know a resource's URI in order to use it.
On modern systems, the server is usually a backend application running on a physical server or in the cloud. The client, on the other hand, is an application running on a web browser or a mobile device. Most web and mobile apps in use nowadays adhere to this principle, communicating with a server using the internet.
2. Stateless
Communication between server and client must be stateless. In other words, all information required to understand a request must be bundled with it. As a result, communication with the backend doesn't need to make use of any context stored on the server. According to Fielding, this approach provides the following benefits:
- Visibility, because monitoring systems only need to look at a request to understand it.
- Reliability, because it's easier to recover from partial failures when there is no volatile state on the server.
- Scalability, because the server doesn't need to manage/store data across requests, making it easier to release resources.
When state is required, the client keeps it (usually as a cookie) and sends it on each subsequent request.
Although this approach provides important benefits, it's important to also consider its drawbacks:
- Sending repetitive data on each request increases network usage.
- The server loses some control over consistent application behaviour, as correct client implementation becomes more important.
3. Cacheable
This means, in essence, that you must label data within a response as cacheable or non-cacheable. The main benefit is a better overall performance by sending fewer requests to the server thanks to the cached values. The cache must manage data properly, otherwise, it will become stale and outdated.
4. Uniform Interface
Probably the most important constraint of the REST architectural style. It requires the system to present a uniform interface between components. Due to the regularity offered by keeping a uniform interface, the architecture of the whole system becomes much simpler. On the other hand, all data must fit a standardized form, something that can degrade efficiency. There are 4 principles that ensure uniformity:
- Identification of resources: resources need to have a unique identifier, enabling you to retrieve and operate on any of them.
- Manipulation of resources through representation: resources can be sent to the client in different formats, such as JSON, XML, PNG, which are representations of such resource. Because REST apps can support several representations for the same resource, clients can indicate which one they wish to receive. Afterwards, you can add and update resources by sending representations of the chosen from the client to the server. For example, a service can let you create a 'Person' by accepting any of the following representations:
{
"Person":{
"name": "Person Example",
"occupation": "Test subject",
"age": 23,
"interests": ["be useful", "serve as example"]
}
}
<Person>
<Name>Person Example</Name>
<Occupation>Test subject</Occupation>
<Age>23</Age>
<Interests>
<Interest>be useful</Interest>
<Interest>serve as example</Interest>
</Interests>
</Person>
- Self-descriptive messages: client requests and the server responses are called messages. Having self-descriptive messages means they include all the information needed to make sense of them. Most implementations of REST accomplish this by providing standard methods (like HTTP's actions) and using media types to indicate semantics.
- Hypermedia as the engine of application state: the term hypermedia refers to any content that has links to other content or media. In REST, server responses usually include hypermedia links, enabling clients to traverse resources through them. Furthermore, requests for a resource usually include links to alter its state. For example, implementations using HTTP routinely include links to send POST and PUT requests to alter or create a resource. In essence, REST provides you with a way to alter the application state by making use of hypermedia.
5. Layered system
This is the classical approach of designing the system in layers. The system is a hierarchy where every layer's components have specific goals and behaviour. Equally important, any component can't see beyond the immediate layer with which they interact.
6. Code on demand (optional)
This means RESTful services can return executable code if there's a need to do so. The main goal is to reduce the number of functionality clients need to implement by letting them download it afterwards. In modern web development, you can consider downloading and executing javascript as a form of code-on-demand. Fielding considers this an optional constraint, your service can be REST even if it doesn't provide code-on-demand features.
Good, but what about GET, POST and all that?
REST and HTTP are not the same things; the former is an architectural style while the later is a protocol. There is a common misconception that all RESTful APIs should use HTTP verbs like GET, PUT and POST. In truth, you can use any stateless protocol and call your API RESTful as long as it abides by the constraints.
Fielding never mentioned any specific protocol to implement RESTful services. However, the usage of HTTP in the transport layer is widely supported by software libraries and server infrastructure. As a result, most, if not all, RESTful services nowadays use HTTP instead of other protocols.
It's useful to know the basics
Because of its huge popularity, REST is a term you will hear over and over if you work on web development. Knowing that REST is more than just receiving and responding to HTTP verbs is already more than most people know about the topic. So, to recap what we have just learned:
- REST is an architectural style for building hypermedia systems
- The resource is the main information abstraction in RESTful systems
- Resources and their representations are decoupled entities
- The goal of REST is to achieve a scalable, fault-tolerant and extensible system by enforcing a special set of constraints
- A system is RESTful if it abides by the guiding constraints established by Fielding
- REST and HTTP are different things, the latter is a protocol
- A system can use stateless protocols other than HTTP and still be RESTful
I hope that reading this will be as useful for you as writing it was for me.
What to do next:
- Share this article with friends and colleagues. Thank you for helping me reach people who might find this information useful.
- Read Roy Fielding's original work.
- You can find helpful books to continue investing in your carrer in the recommended reading list.
- Send me an email with questions, comments or suggestions (it's in the About Me page). Come on, don't be shy!
