A straight to the point introduction to REST – representational state transfer

By | December 29, 2017

REST is here introduced in an as short as possible, but not shorter, fashion.

Representational state transfer

The following explanation of REST is based on the book “The Agile Architecture Revolution” by Bloomberg and Schmelzer 2013, chapter 8. The term representational state transfer (REST) was introduced and defined in 2000 by Roy Fielding in his doctoral dissertation.

REST is an architectural style, which can be viewed as a set of constraints on architecture. These constraints restrict the ways that the server may process and respond to client requests. A service that meets all of these constraints can be called RESTful.

Like Web Services, RESTful services commonly use HTTP for server-client communication and can also use other protocols. In REST, the same computer may serve both the client and the server role at once, while the common pattern of separate clients and servers is most often used.

Definition of necessary terms

To explain REST, even in the form of a summary, some terms must first be defined:

Internet media types

A standard for specifying media types transmitted on the Internet.
Previously known as MIME types.
For example text/html, application/pdf, image/jpeg and application/vnd.mycompany.user.v1+json.

Hypermedia

A generalization of the term hypertext, known from the Web as text documents with links to other text documents, that means media with links to other media. The media can be text, data, graphics, video or audio.

Resource

An abstraction of an entity or capability on a network, addressed through a URI. A service can be a resource. Example resources are a web page, an image, and a service that provides information about a customer.

URI

The Uniform Resource Identifier, comes in two types. Uniform resource locators, URLs, a standardized way of specifying a resource on a network, and how to access it. For example http://www.google.com, http://api-gw.corp.com/customers/123861231/, and ftp://server.com/pub/file.xml (accessed by the http and the ftp schemes). The URI concept also includes Uniform Resources Names (URNs) that identify resources by name in a particular namespace, for example urn:isbn:9780747560722. URNs in contrast to URLs don’t specify the location of the resource or how to access the resource.

Representation

The data and (optionally) metadata that a client receives when requesting a resource. Examples are a web page, an image, and a structured document representing a customer’s information. The representation of the resource must have a format, or encoding, as the client must know how to interpret the data in order to do anything with it. This format metadata is most commonly transferred as an Internet media type, for HTTP.

RESTful applications defined

With these terms defined, we can define a RESTful application as a distributed hypermedia application that adheres to the REST architectural constraints.
These constraints are listed below:

  1. Client-Server. A client-server architectural style is used in order to promote separation of concerns. Fulfilled by HTTP.
  2. Stateless. The client-server interaction is constrained in the following way: communication must be stateless in nature such that each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
  3. Cache. The data within a response to a request must be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests. Fulfilled by HTTP.
  4. Layered system. Clients may connect to the end servers through one or more intermediary components (layers). Each component cannot ”see” beyond the immediate layer with which they are interacting. Fulfilled by HTTP.
  5. Uniform interface. The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components. The uniform interface constraint replaces the tightly-coupling operations of Web Services with a set of predefined verbs. This way, REST moves the operations out of any formal contract. For HTTP, which is the hypermedia protocol most frequently used for REST, the verbs are get, post, put and delete. These verbs query or change some state of a resource. The further decomposition of this constraint is important to understand its consequences, and is shown below:
    1. Separation of resource from representation. The representation of a resources are conceptually separate from the resources themselves. For example the representation may be a document of type text/xml, while the internal representation of the data is in the format of the server’s database.
    2. Manipulation of resources through representations. When a client holds a representation of a resource, including any metadata attached, it has enough information to modify or delete the resource (provided it has permission).
    3. Self-descriptive messages. Each message includes enough information to describe how to process the message. For example, which parser to invoke may be specified by an Internet media type.
    4. Hypermedia as the engine of application state (HATEOAS). The interaction of a client with a RESTful application must be driven by hypermedia, meaning that the client starts by requesting a representation of the resource at a starting point, at a URI called a bookmark, or for APIs, a baseURI. From the links in that representation, the client receives information about the resources available to it, which may include resources that are services. From those resources again, the client may receive links to other resources.

Bloomberg et al. advocates to not dogmatically follow all REST constraints unless this is thought to add value for the specific architecture in question, and also points out that without satisfying the HATEOAS constraint, the benefit of truly loose coupling is lost.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.