REST (Representational state transfer) was first introduced in Roy Fielding's doctoral dissertation Architectural Styles and the Design of Network-based Software Architectures, and it is described as an architectural style for distributed hypermedia systems. It is important to notice two key points here:
- It is an architectural style, not a protocol. For example, SOAP is a protocol. REST, on the other side, is an architectural style which make use of standards, but there is no official standard for REST. Because of this, we often find different solutions to a given problem.
- It is for distributed hypermedia systems. Clients have access to hypermedia information from a repository which might be in a distributed network.
In REST, we define resources (for example, books), that can be represented in a variety of forms (namely, XML, JSON or even protobuf). When we talk about state, we are referring to the current data or version of a resource. Taking this into account, REST is just a means for two systems to transfer the state of a resource through one of its representations.
Note: we've covered resource states. We also have the application state, which resides on the client side. It can transition to other states just following the links in the representations.
REST encompasses six constraints:
- Client-Server - the principle behind this is the separation of concerns provided by this architectural style.
- Stateless - a stateless communication --session state is kept on the client-- leads to visibility, reliability and scalability.
- Visibility - If we use a visible protocol, like HTTP, other components like a firewall or a proxy, can monitor and collaborate.
- Scalability - Since the server does not store any state, a certain request can be handled by any server.
- Cache - this reduces the number of interactions, which improves the efficiency and thus the user experience.
- Layered System - or Microservices. Clients can only see the immediate layer they are interacting with. This layer may be composed of a hierarchy of layers.
- Code-On-Demand (optional) - servers can provide clients with executable code (scripts).
- Uniform Interface - consists in a common, consistent interface to let each side (client and server) evolve independently. Here is a list of each constraint:
- Identification of resources - each single resource has an identifier.
- Manipulation of resources through representations - resources state can be manipulated by a client using a representation.
- self-descriptive messages - each message gives precise information about how to describe itself.
- Hypermedia as the engine of application state (HATEOAS) - Application state transition are carried out through hypermedia in the resource returned by the server.
Resources can be any information that can be named: a document, a collection of documents, a temporal service ("today's weather in Madrid"), etc. There is no consensus about how to model resources, but very often the following patterns are suggested (please note, this is not part of the REST specification):
- Document: Represents a single piece of information (like a row in a database), and can be composed of value-fields and links. For example, a specific university, like "Universidad Rey Juan Carlos" can be a document resource.
- Collection: A collection resource is a container of other resources. Clients can request to create a new resource into the collection, but it's up to the server whether to create it or not. The identifier of the resource is generated by the server.
- Store: As collections, store resources works as repositories of resources. But unlike collections, the creation of the resource is client-managed, which means the identifier is provided by the client.
- Controller: Controller resources can be thought as remote methods: they represent an action, accept input parameters and return a value. These can be used to map procedures that do not match any CRUD action, for example to run a number of operations (merge two contacts), or to carry out an operation whose matching CRUD action is not obvious. Each of these resources will have their own identifier to avoid tunnelling.
By tunnelling we mean using the same operation on the same identifier to perform different actions. SOAP over HTTP or XML-RPC are examples of tunnelling, because they use POST calls to a single URI to perform different operations: they both would delete a resource performing a POST call.
In spite of the large number of benefits of such architecture, REST is not free from criticism:
- Resources usage. True REST services might require a high load of network traffic: (1) to auto-discover available services, (2) the payload is often expressed in XML or JSON and (3) since most of the time is browser oriented, it does not leverage HTTP2.
- Cost of development. It forces developers to choose how they want to represent their resources, how they want to expose links, how to create searchers, etc.
- Data-oriented. Classic RPC technologies are action-oriented, which for some is easier to understand, and find resource-oriented APIs unnatural. There is no consensus on this though.
- Representations. Most programming languages are able to effectively work with either XML, JSON or any other common extended format. Because of this, there is no real need to let users choose how they want to represent a resource.
- Hard to understand. True RESTful APIs are not that common. Because of it's lack of adoption, training both a server-side and a client-side teams to work on a RESTful API can be expensive.
The above constraints are not tight to any specific transfer protocol. They fit perfectly on HTTP, where we work with data (resources), and the behavior results from the operations on that data. When HTTP is used to create a RESTful Service, we call it RESTful Web Service.
REST leaves to the implementer a lot of decisions. Because of this, many standards have been developed:
And many more!
When it comes to the REST constraint about Uniform Interface, this is how each sub-constraint is enforced in a RESTful Web Service:
- Identification of resources - each resource is identified by a URIs (RFC 3986).
- Manipulation of resources through representations - the manipulation of resources state is done through the standard HTTP (RFC 7231). There are no verbs in REST, but not because HTTP already has verbs, but because we are transferring a state, rather than calling instructions.
- self-descriptive messages - the Media Type Specification (RFC 6838) (formerly known as MIME types) is used to make messages self-descriptive. In addition, a schema definition like JSON Schema can be used.
- Hypermedia as the engine of application state (HATEOAS) - hyperlinks in the resource returned by the backend can be used to allow clients to transition from one state to another.
To sum up: resources have identifiers (URIs), and we can leverage the underlying transfer protocol (namely, HTTP) to modify (for example, using PUT) a resource (i.e. change its state) using its representation (for example, a JSON object). These actions are carried out following the hyperlinks of the response.
The so called Richardson Maturity Model describes different levels on how RESTFul a Web Service is:
- Level Zero - One URI and one HTTP method. Example: XML-RPC or SOAP.
- Level One - Many URIs and one HTTP method.
- Level Two - Many URIs and multiple HTTP methods.
- Level Three - Hypermedia: leverage links and forms.