Summary of REST (Excerpts from Fielding's Disseration, summary < 1500 words)

I would like to give something back to the WEB400 list. So here is a brief summary of the REST architectural constraints as originally defined in Roy Fielding's dissertation, which is available for free online at https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf. This summary is based on excerpts from Fielding's dissertation.

Before I begin with the summary, I would like to offer some caveats:
1. REST is not the only legitimate architecture for designing solutions. One doesn't have to REST at all.
2. REST has limitations and is therefore not the best architectural design for all solutions.
3. REST is not all-or-nothing. A particular solution can conform to some REST constraints while violating other REST constraints.
4. Concepts of REST may change over time, which is fine by me. I am simply summarizing REST as it was originally defined in Fielding's dissertation.


REPRESENTATIONAL STATE TRANSFER (REST)

There are 6 architectural constraints in REST:
1. Client-Server
2. Statelessness
3. Cache
4. Uniform Interface
5. Layered System
6. Code-On-Demand


1. Client-Server Constraint

1.1 Description of the Client-Server Constraint

[Fielding]: "The first constraints added to our hybrid style are those of the client-server architectural style (Figure 5-2), described in Section 3.4.1. Separation of concerns is the principle behind the client-server constraints." (p. 78)

1.2 Purpose of the Client-Server Constraint

[Fielding]: "By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components. Perhaps most significant to the Web, however, is that the separation allows the components to evolve independently, thus supporting the Internet-scale requirement of multiple organizational domains." (p. 78)

1.3 Tradeoffs of the Client-Server Constraint

Fielding does not mention tradeoffs of the client-server constraint.


2. Statelessness Constraint

2.1 Description of the Statelessness Constraint

[Fielding]: "We next add a constraint to the client-server interaction: communication must be stateless in nature, as in the client-stateless-server (CSS) style of Section 3.4.3 (Figure 5-3), 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." (pp. 78-79)

2.2 Purpose of the Statelessness Constraint

[Fielding]: "This constraint induces the properties of visibility, reliability, and scalability. Visibility is improved because a monitoring system does not have to look beyond a single request datum in order to determine the full nature of the request. Reliability is improved because it eases the task of recovering from partial failures [133]. Scalability is improved because not having to store state between requests allows the server component to quickly free resources, and further simplifies implementation because the server doesn't have to manage resource usage across requests." (p. 79)

2.3 Tradeoffs of the Statelessness Constraint

[Fielding]: "Like most architectural choices, the stateless constraint reflects a design trade-off. The disadvantage is that it may decrease network performance by increasing the repetitive data (per-interaction overhead) sent in a series of requests, since that data cannot be left on the server in a shared context. In addition, placing the application state on the client-side reduces the server's control over consistent application behavior, since the application becomes dependent on the correct implementation of semantics across multiple client versions." (p. 79)


3. Cache Constraint

3.1 Description of the Cache Constraint

[Fielding]: "In order to improve network efficiency, we add cache constraints to form the client-cache-stateless-server style of Section 3.4.4 (Figure 5-4). Cache constraints require that the data within a response to a request 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." (p. 79)

3.2 Purpose of the Cache Constraint

[Fielding]: "The advantage of adding cache constraints is that they have the potential to partially or completely eliminate some interactions, improving efficiency, scalability, and user-perceived performance by reducing the average latency of a series of interactions." (p. 80)

3.3 Tradeoffs of the Cache Constraint

[Fielding]: "The trade-off, however, is that a cache can decrease reliability if stale data within the cache differs significantly from the data that would have been obtained had the request been sent directly to the server." (p. 80)


4. Uniform Interface Constraint

4.1 Description of the Uniform Interface Constraint

[Fielding]: "The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components (Figure 5-6)." (p. 81)

[Fielding]: "In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state." (p. 82)
4.2 Purpose of the Uniform Interface Constraint

[Fielding]: "By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. Implementations are decoupled from the services they provide, which encourages independent evolvability." (pp. 81-82)

4.3 Tradeoffs of the Uniform Interface Constraint

[Fielding]: "The trade-off, though, is that a uniform interface degrades efficiency, since information is transferred in a standardized form rather than one which is specific to an application's needs. The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction." (p. 82)


5. Layered System Constraint

5.1 Description of the Layered System Constraint

[Fielding]: "In order to further improve behavior for Internet-scale requirements, we add layered system constraints (Figure 5-7). As described in Section 3.4.2, the layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot 'see' beyond the immediate layer with which they are interacting." (pp. 82-83)

5.2 Purpose of the Layered System Constraint

[Fielding]: "By restricting knowledge of the system to a single layer, we place a bound on the overall system complexity and promote substrate independence. Layers can be used to encapsulate legacy services and to protect new services from legacy clients, simplifying components by moving infrequently used functionality to a shared intermediary. Intermediaries can also be used to improve system scalability by enabling load balancing of services across multiple networks and processors." (p. 83)

5.3 Tradeoffs of the Layered System Constraint

[Fielding]: "The primary disadvantage of layered systems is that they add overhead and latency to the processing of data, reducing user-perceived performance [32]. For a network-based system that supports cache constraints, this can be offset by the benefits of shared caching at intermediaries. Placing shared caches at the boundaries of an organizational domain can result in significant performance benefits [136]. Such layers also allow security policies to be enforced on data crossing the organizational boundary, as is required by firewalls [79]." (p. 83)


6. Code-On-Demand Constraint (optional)

6.1 Description of the Code-On-Demand Constraint

[Fielding]: "The final addition to our constraint set for REST comes from the code-on-demand style of Section 3.5.3 (Figure 5-8). REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts." (p. 84)

6.2 Purpose of the Code-On-Demand Constraint

[Fielding]: "This simplifies clients by reducing the number of features required to be pre-implemented. Allowing features to be downloaded after deployment improves system extensibility." (p. 84)

6.3 Tradeoffs of the Code-On-Demand Constraint

[Fielding]: "However, it also reduces visibility, and thus is only an optional constraint within REST." (p. 84)


Addendum

Because Fielding considers the Uniform Interface constraint to be the "central feature" of REST, I would like to provide a little additional information concerning the four constraints within the Uniform Interface constraint.

A. identification of resources

[Fielding]: "The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. 'today's weather in Los Angeles'), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource." (p. 88)

[Fielding]: "REST uses a resource identifier to identify the particular resource involved in an interaction between components." (p. 90)

Fielding says a URL is an example of a resource identifier in Table 5.1 on page 88.
B. manipulation of resources through representations

[Fielding]: "REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant." (p. 90)

Fielding says an HTML document and a JPEG image are examples of a representation in Table 5.1 on page 88.

C. self-descriptive messages

HTTP can be used for self-descriptive messages. For more information on how HTTP methods are used for messaging in RESTful architecture, see the following:
http://code.tutsplus.com/tutorials/a-beginners-guide-to-http-and-rest--net-16340
http://restcookbook.com/HTTP%20Methods/idempotency/
http://restcookbook.com/HTTP%20Methods/put-vs-post/

D. hypermedia as the engine of application state (HATEOAS)

Fielding says little about HATEOAS in his dissertation. Fielding says HATEOS is a key feature of REST in a blog post. Hypertext-driven is another way of saying hypermedia is the engine of application state. Be sure to read Fielding's responses in the comments: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven. Here is a YouTube video that does a decent job of explaining HATEOAS: https://www.youtube.com/watch?v=NK3HNEwDXUk.

Thanks,

Kelly Cookson
IT Project Leader
Dot Foods, Inc.
1.217.773.4486 ext. 12676
kcookson@xxxxxxxxxxxx<mailto:kcookson@xxxxxxxxxxxx>