Key notes on the REST architectural style

In the year 2000, Roy Fielding published his doctoral dissertation on the REST architectural style. I am studying REST to evaluate its suitability for enterprise applications in telecommunication billing software domain. Following are some key notes that I excerpted from Roy Fielding’s dissertation. I will be using these notes to do my analysis. Readers can use these notes to quickly familiarize themselves with key principles of REST.

Table of Contents

  1. What are the constraints of the REST architectural style?
  2. What are the reasons behind those constraints?
  3. How to implement those constraints?

What are the constraints of the REST architectural style?

  1. Client-server model
  1. Layered system
  1. Stateless interactions
  1. Response cache
    1. server-side and client-side
    2. Attempts to balance the desire for transparency in cache behavior with the desire for efficient use of the network, rather than assuming that absolute transparency is always required.
    3. Some cache connectors are shared, meaning that its cached responses may be used in answer to a client other than the one for which the response was originally obtained.
  1. Interface
    1. Uniform interface
      1. Resource identifiers
      2. Manipulation of resources through representations
      3. Self-descriptive messages
      4. Hypermedia as the engine of application state
    2. Standard methods and media types are used to indicate semantics and exchange information
    3. Content negotiation
  1. Code-on-demand (optional constraint)
  1. Resource
    1. A resource is the semantics of what the author intends to identify, rather than the value corresponding to those semantics at the time the reference is created.
    2. The resource is not the storage object. The resource is not a mechanism that the server uses to handle the storage object. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
    3. The only thing that is required to be static for a resource is the semantics of the mapping, since the semantics is what distinguishes one resource from another.
    4. There are no resources on the server; just mechanisms that supply answers across an abstract interface defined by resources.
    5. Some resources are static in the sense that, when examined at any time after their creation, they always correspond to the same value set. Others have a high degree of variance in their value over time.
  1. Resource abstraction
    1. The resource implementation details are hidden behind the interface. REST works well because it does not limit the implementation of resources to certain predefined models, allowing each application to choose an implementation that best matches its own needs and enabling the replacement of implementations without impacting the user.
    2. REST ignores the details of component implementation in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.
    3. The protocols are specific about the intent of an application action, but the mechanism behind the interface must decide how that intention affects the underlying implementation of the resource mapping to representations.
  1. Resource representation
    1. The things that are manipulated are representations of the identified resource, rather than the resource itself.
    2. A representation consists of data, metadata describing the data, and, on occasion, metadata to describe the metadata (usually for the purpose of verifying message integrity).
    3. Whether the representation is in the same format as the raw source, or is derived from the source, remains hidden behind the interface.
    4. Many different resources can map to the same representation, while some resources may have no representation mapped at all.
    5. An origin server is the definitive source for representations of its resources.
  1. Resource identifier
    1. A resource identifier identifies a concept rather than a document.
    2. Resource identifiers should change as infrequently as possible.
    3. References can be made to a concept before any realization of that concept exists.
    4. A resource can have many identifiers. In other words, there may exist two or more different URI that have equivalent semantics when used to access a server.
    5. It is also possible to have two URI that result in the same mechanism being used upon access to the server, and yet those URI identify two different resources because they don’t mean the same thing.
    6. Relies on the author choosing a resource identifier that best fits the nature of the concept being identified.
    7. A resolver translates partial or complete resource identifiers into the network address information needed to establish an inter-component connection.
  1. Communication
    1. The connectors present an abstract interface for component communication.
    2. Due to the scale of the Web, in the REST style, consuming components usually pull representations.
    3. Component interactions occur in the form of dynamically sized messages.
    4. Control data defines the purpose of a message between components, such as the action being requested or the meaning of a response. It is also used to parameterize requests and override the default behavior of some connecting elements.
    5. A representation can be included in a message and processed by the recipient according to the control data of the message and the nature of the media type.
    6. Composite media types can be used to enclose multiple representations in a single message.
    7. Response messages may include both representation metadata and resource metadata: information about the resource that is not specific to the supplied representation.
    8. An origin server must be the ultimate recipient of any request that intends to modify the value of its resources.
    9. From an abstract viewpoint the invocation is synchronous, but both in and out-parameters can be passed as data streams.
    10. Requests and responses have the appearance of a remote invocation style, but REST messages are targeted at a conceptual resource rather than an implementation identifier.
    11. REST does not restrict communication to a particular protocol, but it does constrain the interface between components, and hence the scope of interaction and implementation assumptions that might otherwise be made between components. Interaction with various services is restricted to the semantics of a REST connector.
    12. Interaction is improved by protocols that “respond first and think later.”
    13. REST ignores the protocol syntax in order to focus on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements.
  1. State
    1. The application state is controlled and stored by the user agent and can be composed of representations from multiple servers.
    2. Cookies violate REST
  1. The application details are hidden from the server by the generic connector interface. The REST style does not assume that all applications are browsers.
  1. REST captures all of those aspects of a distributed hypermedia system that are considered central to the behavioral and performance requirements of the Web. REST elaborates only those portions of the architecture that are considered essential for Internet-scale distributed hypermedia interaction. REST is not intended to capture all possible uses of the Web protocol standards. There are applications of HTTP and URI that do not match the application model of a distributed hypermedia system.


What are the reasons behind those constraints?

  1. Client-server model
    1. increases the scalability of pure server components
    2. simplifies component implementation
    3. reduces the complexity of connector semantics
    4. improves the effectiveness of performance tuning
  1. Layered system
    1. allows intermediaries – proxies, gateways, and firewalls – to be introduced at various points in the communication without changing the interfaces between components, thus allowing them to assist in communication translation or improve performance via large-scale, shared caching.
    2. allows pipe-and-filter style arrangement of components
  1. Stateless interaction
    1. reducing consumption of physical resources and improves scalability
    2. allows an intermediary to view and understand a request in isolation, which may be necessary when services are dynamically rearranged. Intermediary components can actively transform the content of messages because the messages are self-descriptive and their semantics are visible to intermediaries. Intermediary components can reduce interaction latency, enforce security and encapsulate legacy systems.
    3. allows pipe-and-filter style arrangement of components
    4. forces all of the information that might factor into the reusability of a cached response to be present in each request.
    5. removes the need for an awareness of the overall component topology, an impossible task for an Internet-scale architecture,
    6. allows components to act as either destinations or intermediaries, determined dynamically by the target of each request.
    7. Connectors need only be aware of each other’s existence during the scope of their communication
    8. allows interactions to be processed in parallel without requiring that the processing mechanism understand the interaction semantics
  1. Generality of interface
    1. allows information hiding to enable encapsulation and evolution of services
    2. enables substitutability: if the users’ only access to the system is via an abstract interface, the implementation can be replaced without impacting the users.
    3. enables a cache to determine the cacheability of a response because the interface is generic rather than specific to each resource.
    4. enables intermediate processing
    5. allows pipe-and-filter style arrangement of components
    6. enables access to a multitude of services through a single proxy.
    7. enables independent deployment of components
  1. Self-descriptive messages
    1. enables intermediate processing
    2. allows pipe-and-filter style arrangement of components
    3. persistent connections became possible
  1. Caching reduces interaction latency. Client-side cache avoids repetition of network communication. Server-side cache avoids repeating the process of generating a response.
  1. Resource abstraction
    1. provides generality by encompassing many sources of information without artificially distinguishing them by type or implementation.
    2. allows late binding of the reference to a representation, enabling content negotiation to take place based on characteristics of the request.
    3. allows an author to reference the concept rather than some singular representation of that concept, thus removing the need to change all existing links whenever the representation changes (assuming the author used the right identifier).
    4. allows independent authoring of interconnected hypertext across multiple trust domains.
    5. restricts a client to the manipulation of representations rather than directly accessing the implementation of a resource. Therefore, the implementation can be constructed in whatever form is desired by the naming authority without impacting the clients that may use its representations.
  1. Code-on-demand
    1. simplifies clients by reducing the number of features required to be pre-implemented.
    2. allows features to be downloaded after deployment improves system extensibility.
  1. Connectors
    1. enhance simplicity by providing a clean separation of concerns
    2. hide the underlying implementation of resources and communication mechanisms.
  1. Data streaming avoids the latency of batch processing large data transfers.
  1. “Respond first and think later” – A protocol that requires multiple interactions per user action, in order to do things like negotiate feature capabilities prior to sending a content response, will be perceptively slower than a protocol that sends whatever is most likely to be optimal first and then provides a list of alternatives for the client to retrieve if the first response is unsatisfactory.
  1. “Application state is controlled and stored by the user agent”
    1. frees the server from the scalability problems of storing state
    2. allows the user to directly manipulate the state (e.g., a Web browser’s history) anticipate changes to that state (e.g., link maps and prefetching of representations), and jump from one application to another (e.g., bookmarks and URI-entry dialogs).
  1. “Cookies violate REST”
    1. Cookies provide indirect application state that cannot be managed or interpreted by the user agent
    2. Cookie interaction fails to match REST’s model of application state. The problem is that a cookie is defined as being attached to any future requests for a given set of resource identifiers, usually encompassing an entire site, rather than being associated with the particular application state (the set of currently rendered representations) on the browser.
    3. Cookies allow data to be passed without sufficiently identifying its semantics, thus becoming a concern for both security and privacy. The combination of cookies with the Referer [sic] header field makes it possible to track a user as they browse between sites.
  1. Resolvers improve the longevity of resource references through indirection, though doing so adds to the request latency.


How to implement those constraints?

  1. “How a well-designed Web application behaves” – A network of web pages (a virtual state-machine), where the user progresses through the application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.
  1. Stateless interaction
    1. Each request contains all of the information necessary for a connector to understand the request, independent of any requests that may have preceded it.
    2. All of the control state is concentrated into the representations received in response to interactions.
  1. Caching
    1. The cache connector, can be located on the interface to a client or server connector in order to save cacheable responses to current interactions
    2. By default, the response to a retrieval request is cacheable and the responses to other requests are non-cacheable. If some form of user authentication is part of the request, or if the response indicates that it should not be shared, then the response is only cacheable by a non-shared cache. A component can override these defaults by including control data that marks the interaction as cacheable, non-cacheable or cacheable for only a limited time.
  1. Content negotiation – components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource.
  1. Manipulation of resources through representations – 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.
  1. Parameters and results – The connector interface is similar to procedural invocation, but with important differences in the passing of parameters and results. The in-parameters consist of request control data, a resource identifier indicating the target of the request, and an optional representation. The out-parameters consist of response control data, optional resource metadata, and an optional representation.
  1. “Resource identifiers should change as infrequently as possible” – A resource is defined to be the semantics of what the author intends to identify, rather than the value corresponding to those semantics at the time the reference is created. It is then left to the author to ensure that the identifier chosen for a reference does indeed identify the intended semantics.
  1. Request processing – A resource is a conceptual mapping to a set of entities. The server receives the identifier (which identifies the mapping) and applies it to its current mapping implementation (usually a combination of collection-specific deep tree traversal and/or hash tables) to find the currently responsible handler implementation and the handler implementation then selects the appropriate action+response based on the request content.


This entry was posted in REST and tagged . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s