Remembering the Future

“The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components”

That uniform interface is defined by four interface constraints

1. Identification of resources
2. [direct] manipulation of resources through representations
3. self-descriptive messages
4. hypermedia as the engine of application state

These constrains enforce a specific kind of “uniform interface” to guide the behavior of application components. The motivation for using these constraints is to simplify system architecture and improve the visibility of component interactions.

“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.” (from the infamous Roy Fielding Dissertation)

This leads to systems that are architected with REST applications to cross organizational boundaries, where specific APIs cannot be controlled by a single authority, and more efficient object-oriented architectures to support processing within a specific organizational and workflow processing context. The optimal split between REST and object oriented architectures can be a difficult decision to predict. For workflow applications, one of the most interesting constraints to consider is: “hypermedia as the engine of application state”.

REST designs emphasize that, by clicking on links you should be able to access an application’s representation without having to “remember the history of choices" or "hidden state" in order to know how to interpret that representation.

The easiest way to do this is to have a single URL that returns the entire application representation.

If this is too large, you can divide the representation into smaller pieces that are connected by URLs. A chapter index provides a metaphor for a set of links that represent the entire document and provide access to each piece as a navigational choice. You can also provide partially expanded views, where one or more of the chapters of the index are expanded into content.

If it isn't possible to have a link to every part of the representation in a single step, you should at least make sure that the representation is fully connected, allowing access to any part of the representation through multi-step link paths. One simple example is a document where each page has a previous and next page link. If the document is transformable, however, things can get a little more complicated. If you change a piece of a document, you can disrupt links that point to it. In the worst case, this fragmentation will inadvertently divide the representation into pieces that are no longer connected.

It is also possible to connect the URLs of an application through some kind of URL based query facility. This provides a novel definition of what is an application. A REST application is defined as a collection of mutually connected URLs. As new URLs are added to the representation, if those URLs provide a path back to all the other URLs in the application (possibly over many steps or through a URL based query function), then that newly added URL and its supporting process are added to the definition of the application.

This means that the URLs returned from a Google search, are not part of the Google REST application, unless they have a link that points back to the Google query screen. A reporting application that has a home page which list existing reports, and allows you to search and create new reports, would only included the generated reports as part of its REST application, if those reports had a link back to its application home page. Otherwise, it would just be an application that listed, created and searched external resources.

In order to keep application boundaries clear, a Web resource should not make changes to Web resources that are not connected to it. Any data that is modified behind the veil of the URLs supporting process however (like object oriented APIs and database tables), would generally be considered part of the process application even if they are not accessible from a URL, but they would not be part of the “REST application”.

A similar argument applies to REST Services Oriented applications. A GET on a REST Web Service should return a view of the piece of the application state that is being managing, and support POST, PUT, or DELETE to modify its state. Any newly created resources should link back to the generating application process. Deleting resources should not split the applications network of links into disconnected islands.

REST Workflow applications, would generally have a list and query resource for managing workflow instances. Each workflow instance would then provide a URL backed resource for managing the individual workflow instance. All processes that modify the state of a workflow instance, should annotate that portion of the workflow state with their process URL. A GET on that process URL should return a view of that portion of the representation that is being managed along with links (or views) to the rest of the application state. Whether there are additional application constraints, consistent with BPEL or other workflow languages, is not really relevant to REST architecture.