What is REST? Part 2: RESTful interfaces

What is REST? Part 2: RESTful interfaces

RESTful architecture: Revisiting

In his dissertation, Roy Fielding defines RESTful architecture as a uniform layered client-cache stateless server. You’ll find a detailed description of this in Part 1 of this series.
It is no coincidence that Fielding places uniform at the front; for him, this is the most important distinguishing attribute of RESTful architecture.

A uniform (RESTful) is distinguished by the following four properties (constraints):

  • Identification of resources

  • Manipulation of resources through representations

  • Self-descriptive messages

  • Hypermedia as the engine of application state

Identification of resources

A resource is any type of information clients can access via hyperlink. On that point, Fielding writes in his dissertation:

(…) any concept that might be the target of an author’s hypertext reference must fit within the definition of a resource.

To cite an example, if a server is administering a customer database, then that server could indeed offer the resources of both CUSTOMER and LIST OF CUSTOMERS. Each resource can be addressed via a unique identifier. In the context of a distributed hypermedia system (web), a link functions as a resource identifier. In today’s Web, identifiers would have the following structure:

  • CUSTOMER: path/customer/[customer_id]
  • LIST OF CUSTOMERS: path/customer

Since the identifier has the effect of unique identification of a resource, the identifier should be static. For customer number 123, the identifier should always be path/customer/123 . By contrast, a resource can be dynamic. That means a resource’s attributes can indeed change. If a customer with customer number 123 is living in Hamburg at time A and in Berlin at time B, then the client would receive different manifestations of this resource at time A and B (the “location” attribute would change). In this context, Fielding also speaks of a single resource having different states.

Das Schaubild zeigt unterschiedliche Zustände einer Ressource

Manipulation of resources through representations

When a client uses a link (i.e. the identifier) for a resource request, the server’s response is not the resource itself but rather its representation. According to Fielding, a representation is a sequence of bytes and meta data describing the bytes. In this context, the representation is a kind of data format of a resource. A server can have multiple representations of the same resource. During a request, the client can communicate to the server which representation (i.e. which data format) it is expecting in the response. The following example demonstrates how the server supplies different representations of the resource CUSTOMER for different clients: XML and JSON. The clients use the HTTP Header CONTENT-TYPE to communicate the desired representation. Fielding introduces the term “content negotiation” for this transaction.

Das Schaubild veranschaulicht den Zugriff der Clienten auf die Repräsentationen

Clients can not only request resources, they can also modify them. Here, too, clients do not access the resources directly, but rather their representations. This principle has the advantage of clients not having to understand the technical implementation, rather only have a “technical understanding” of the representation.

The two attributes described above were key for the naming of REST: REpresentational State Transfer. Accordingly, the point here is that a resource can have different states, and that client and server share the representation of these states.

Self-descriptive messages

RESTful architecture is layered: it consists of multiple components that communicate with one another and fulfill different roles. Communication involves not only a client (sends request) and a server (provides response), but also special components that forward requests and responses. In this context, Fielding speaks of gateways and proxies. A self-descriptive message contains all information necessary to be processed via client, server, proxy and gateway.

In the context of HTTP, each request has a series of headers describing certain attributes of an HTTP message. In HTTP-based communication, every component involved exclusively uses the kinds of HTTP headers that are necessary for processing the message and thus correspond to those components’ task. Accordingly, based solely on a message’s content type, the client knows which parser to use for processing (e.g. XML or JSON).

Hypermedia as the engine of application state

Hypermedia as the engine of application state (generally abbreviated HATEOAS) is the most commonly misunderstood constraint in REST interfaces. This comes as no surprise: Although Fielding does make mention of HATEOAS in his dissertation, he does not supply any clarifications. One of Fielding’s blog articles laments the lack of comprehension regarding HATEOAS and underscores its importance:

What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API.

Fielding understands HATEOAS to be the way in which clients use a REST interface. Specifically, the client is supposed to “enter” a REST interface via a gateway that is generally known. The server notifies the client via hypermedia of which resources the interface offers, and which actions are possible for those resources. The client executes actions, thereby changing the status of a resource (to be more precise: the status of the representation of a resource).

The following figure illustrates HATEOAS in action. As an example, we’ll use the customer database introduced in the sections above. The client initially opens a list of all customers and uses the identifier /customer. The server’s response delivers a customer list consisting of two entries: Customer with ID=123 and customer with ID=456. Each of these entries contains a link to the respective customer (rel=“self“) and their orders (rel=“orders“). The client would like to know which orders the customer with ID=123 has placed and opens /customer/123/orders. The server sends back the orders with ID=1. In addition to reference to the order, the response itself contains two further links: the client can open details or cancel the order. After each request, the server notifies the client of which further actions are possible. The client can use the interface to navigate exploratively and does not have to remember the links in advance.

Die Abbildung zeigt die Funktionsweise von HATEOS


According to Fielding, a RESTful interface is distinguished in that clients can manipulate resources through representations. The technical implementation details of resources remain hidden to clients: This is an important prerequisite for loose coupling between client and server. Further constraints are self-descriptive messages and particularly HATEOAS. HATEOAS involves the use of hypermedia for communication between client and server. Meeting the constraint HATEOAS is an important prerequisite for any RESTful interface.

Author: Nicolai Zaidman

Read more


With Q_PERIOR, you have a strong partner at your side.
We look forward to your challenge!