REST: The 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. (Fielding’s Dissertation, Sec. 5.1.5)

Street RESTers will immediately submit that the uniform interface is simply having a URL that reads: “/controller/method/id”.  While this maps nicely to their server-side MVC application, it does not represent the necessary constraints to satisfy the uniform interface of REST.

In the dissertation Fielding defines four interface constraints for REST:

1. Identification of resources
2. Manipulation of resources through representations
3. Self-descriptive messages
4. Hypermedia as the engine of application state

The benefits realized by the uniform interface are best understood in terms of the effects upon the architecture when applying these constraints.

Identification of Resources

To understand this constraint we must first have a solid definition of a resource.  A resource is some named entity that is provided by our application.  On the web we generally use URLs to name these entities.  The normal notion of a URL is “a link to a web page”.  A URL is a special kind of Uniform Resource Identifier.  REST constrains the URIs we use in a few ways:

• The semantics of the mapping of a URI to a resource must not change.  So, while the contents of example.com/Top10 can change over time, the thing that it names—e.g. the top 10 examples of the day—cannot.
• A resource’s identity is independent of its value. So, two resources could point to the same value at some point in time, but they are not the same resource.
• The provider of a resource is solely responsible for maintaining the semantic validity of the URI.  This just means that we should choose good URLs that are easy to maintain.
• A URI should not contain any reference to the media type used to represent the resource; example.com/Top10/json is verboten.

This seems like a simple constraint, and it is, but its significant benefits include:

• There is just one way to get at a particular resource.
• The value of a resource at a point in time (representation) can be served up in any appropriate media type at the time it is requested, based on the characteristics of the request (Accept header).
• Since the semantics of resource identifiers are static, and the media type of the representation is determined at the time of the request, clients dependent on a resource do not have to change any identifiers in order for the content type to change.

Manipulation of Resources through Representations

The abstract notion of a resource named by a URI is reified by a representation in a media type selected based upon the nature of the request for that resource.  A representation contains the data and metadata describing the data, such as the media type of the data.  All of the perceived work done by a server in REST architecture is initiated by a client either: a) requesting a resource whereupon the server returns a representation of that resource; b) sending a representation of a resource whereupon the server nominally mutates/creates the resource.

There are additional details to the semantics of representation-based interactions, but the salient point is that URLs are not akin to call sites in a program.  These interactions are more akin to message passing.

An important and often overlooked consequence of this constraint is that there is no distributed consistency, and so the notion of a “transactional REST” is anathema:

REST just says that there is no consistency -- only representations that indicate state at some point in the past and an implicit grant of use for some time into the future. –Fielding on rest-discuss

Besides decoupling the resource from a particular representation, the benefit to this approach are seen in the application of the next two constraints.

Self-Descriptive Messages

All of the details required to route, interpret, and process a message must be in the message itself.  This enables the communication between components to be stateless and allows messages to be cached appropriately.

REST concentrates all of the control state into the representations received in response to interactions. The goal is to improve server scalability by eliminating any need for the server to maintain an awareness of the client state beyond the current request. (dissertation)

Hypermedia as the Engine of Application State

The model application is therefore an engine that moves from one state to the next by examining and choosing from among the alternative state transitions in the current set of representations. (dissertation)

This is probably the least applied of the REST constraints, especially with the proliferation of AJAX clients. The core idea is that the representation given to the client will have embedded hyperlinks that completely disambiguate what actions are available to interact with the server.

Dr. Fielding wrote an extended exposition of the hypermedia constraint wherein he makes explicit some rules that apply to a RESTful API.  He also says this,

A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure). Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources).

Lest you think you can apply REST to your architecture sans this “hypermedia constraint”, Dr. Fielding further clarifies.

ROA is supposed to be a kind of design method for RESTful services, apparently, but most folks who use the term are talking about REST without the hypertext constraint. In other words, not RESTful at all. REST without the hypertext constraint is like pipe-and-filter without the pipes: completely useless because it no longer induces any interesting properties. (blog)

Towards a RESTful Client

Taken together, the constraints that engender the uniform interface of REST-style architecture, in turn force certain characteristics in clients of a RESTful API.  Among these client characteristics are:

• Ability to process one or more media types available for a resource’s representation.
• Ability to maintain and manage state by selecting among hyperlinks.
• Awareness of potential inconsistency of representations.
• Only enters the interaction from a known entry point.

If we are building RESTful web applications, we have to supply such a client that can run in a browser.  For example, the user agent can navigate to the URL that identifies the client. This client is assembled in the browser via normal mechanisms for displaying a web page.  The various JavaScript libraries loaded then augment the capabilities of the browser to exhibit the characteristics mentioned above while interacting with the RESTful API on the server.