The Connectedness Principle in REST

We are currently in the process of implementing REST services for our FileCatalyst Webmail and Workflow products. While implementing these services I started looking around to see what others are doing in this space. One thing that became apparent is the lack of the “connectedness” or “link” principle (as defined by Roy T. Fielding’s dissertation ) for REST services.

Properties of REST

Addressability

  • An application is addressable if it exposes the interesting aspects of its data set as resources.
  • An addressable application exposes a URI for every piece of information it might conceivably serve.

Statelessness

To eliminate state from a protocol is to eliminate a lot of failure conditions. The server never has to worry about the client timing out, because no interaction lasts longer than a single request. Clients never have to worry about performing actions in the wrong order, because of some state kept on the server. A RESTful service is “stateless” if the server never stores any application state. Hence, a stateless application is easy to scale and cache.

Application State

  • Information about the path the client has taken through the application
  • Lives on the client and is client specific. A web service only needs to care about a client’s application state when actually making a request. Since this information is client specific, it needs to be included in the request.
  • example: application or API key that is required for every web service request.

Resource State

  • Resource state for all clients which lives and stays on the server.
  • Sent to the client in the form of representations.

Connectedness

RESTful services representations are hypermedia documents. These are documents that contain not just data, but links to other resources. The server guides the client’s path by serving “hypermedia”: links and forms inside hypertext representations. The server sends the client guidelines about which states are near the current one. The quality of having links is called “connectedness”. Resources should link to each other in their representations. Hence, why the human web is easy to use because it is well connected.

For instance, Amazon S3 is a RESTful web service that is addressable and stateless, but not connected. S3 never includes URIs.

Uniform Interface

A resource is anything that’s important enough to be referenced by itself. “Resource” is about as vague as “thing”, so any kind of data or algorithm you want to expose can be a resource. If you might want to make a hyperlink to it then you should make it a resource. There are three types of resources:

  • Predefined one-off resources, such as the service’s home page.
  • A large (possibly infinite) number of resources corresponding to individual items of data of the same type (database rows, objects in object-oriented systems).
  • A large (probably infinite) number of resources corresponding to the possible output of an algorithm. For instance, the list from a search engine.

The URI is simply the name or address of a resource. If a piece of information does not have a URI, it is not a resource. Every URI designates exactly one resource. URI’s should be descriptive and structured and by definition no two resources can be the same. If they were the same, you would only have one resource. However, at some moment in time two different resources may point to the same data. A resource may have one URI or many. URI are supposed to designate resources, not operations on the resources. This means it is never appropriate to put the names of operations in the URI. If you have an operation in the URI, this is probably indicative of an RPC-style service.

Hypermedia and RESTful Services

For the most part the Addressability, Statelessness, and Uniform Interface properties of most REST services are adhered to. It is the “connectedness” property that is the most abused.

The hypermedia part of RESTful Services is what contains the “connectedness” information for resources on the Web. On the Web, the life cycle of a single resource is more than the creation, updating, reading, or deleting of that resource. Metadata about the resource, the subset of the verbs it understands, and information about other resources we might want to interact with can also be part of the state returned with that resource. Links or “connectedness” is good in Web-based systems and yet it seems to be the most forgotten aspect of many RESTful services. These links act as state transitions and the application conversation is captured in terms of these states.

Basically one is describing programmatic contracts with the defined links. For instance, links on a normal Web page (accessed via a browser) constitute a contract for page traversals. The same is true of the programmatic Web. One can use the links to describe state transitions in programmatic Web services. By navigating these resources you change the application state by following those links. This is the definition of a state machine! These same links can lead to other resources which also have links, and so on.

Why are links important? Links describes Protocols. Links declare next valid steps. This is HATEOAS (Hypermedia as the Engine of Application State)!

Conclusion

Although REST services which do not offer links to interesting and related information can still be very useful, they, in my opinion are not 100% RESTful. Hence, do not forget to include links to your response payload and you will fulfill the “connectedness” REST principle and become 100% REST compliant.