REST, RDF and Hypermedia

REST

Representational state transfer or REST defines a number of architectural constraints, which when applied allow building software, which is fast, scalable and simply interacted with.

TL;DR; RESTful application works very much like the Internet. A client requests a known resource by its identifier and follows links included in the representations to move to another state. No further information should be required by the client to know except the initial identifier.

REST constraints

As summed up on wikipedia, to implementa RESTful application a number of constraints must be fulfilled:

  1. Client-server - interface separates clients from servers
  2. Stateless - server stores no client information between requests
  3. Cacheable - allow and declare responses as cacheable, to improve performance
  4. Layered system - transparently stack intermediate proxies on top of the server
  5. Uniform interface
  6. Code on demand (optional)

With the Web and HTTP being the usual transport for implementing a RESTful service, constraints 1 through 4 are generally understood. Also they are realized by components outside the scope of programmers such as proxies, servers, load balancers. Of course implementors must follow a set of rules to create a well-bahaved service, but the first four constraints generally cause least excitement and are well accepted. That is also partially true for the Uniform interface constraint. However it is the crucial component and also very much different from the typical RPC architectural and behavioral styles, it also causes most misunderstanding and heated discussion. Uniform interface states that:

  • resources must be identified be identifiers, and that thy are separate from the resource representation
  • the representation must be used to manipulate resources
  • clients must communicate with the server using self-descriptive messages, that is the these message contain all information required to precess that request
  • the client chooses state transitions from alternatives included in the representations (Hypermedia as the engine of application state aka HATEOAS)

Lastly there is the only optional constraint, which states that servers can include (small?) fragments of code for the clients to execute. These could be snippets in javascript or another scripting language, Flash components or even compiled code in Java or another language.

RDF

With the advent of the Semantic Web many have seen RDF as means to create RESTful services. What is RDF? A short for Resource Description Framework, here’s how it’s described on wikipedia:

The RDF data model is similar to classic conceptual modeling approaches such as entity–relationship or class diagrams, as it is based upon the idea of making statements about resources (in particular web resources) in the form of subject-predicate-object expressions.

That subject-predicate-object expressions, called triples are the atoms of data in description of a RDF resource. For example triple like

1

<http://t-code.pl/about#tomasz> <http://xmlns.com/foaf/0.1/name> "Tomasz Pluskiewicz" .

means that there exists a resource identified by URI http://t-code.pl/about#tomasz (subject), whose name (predicate) is Tomasz Pluskiewicz (object). It is important to note that the predicate name is also identified by a URI and thus is a resource itself too. This means that not only data can be shared but also the nature of that data, which in an ideal world should allow clients to better understand that data and reason upon it. This is in fact a one of the premises of the Semantic Web!

RESTful RDF?

RDF does seem like a good match for REST. It it a logical extension to the existing Web. It uses URI identifier for resources and those resources are decoupled from their representations. RDF resources can be represented using a wide selection of serialization formats like Turtle or JSON-LD. Unfortunately RDF itself falls short of fulfilling the complete set of REST constraints, because in itself it’s not a hypermedia type. Hypermedia types are defined by Mike Amundsen as follows

Hypermedia Types are MIME media types that contain native hyper- linking semantics that induce application ow. For example, HTML is a hypermedia type; XML is not.

The most commonly used MIME for current Web Apis, JSON also is not a hypermedia type. This causes the clients to require out-of-band information to interact with a service. Bare RDF is almost good enough to build read only API. For example, given a triple (base URI) We could attempt to retrieve a representation of the resource. But what if the resource is a web page (ie. has only a HTML representation available). Information about the nature of this resource could be defined in the description of the property, but RDF has no standard way of defining hypermedia semantics. A bigger problem is encountered when one tries to build a read-write API based on RDF. For example here’s a list of users interests (in Turtle):

1

</tomasz> <interest> "rdf", "semantic web", "c#" .

How do we state that a new item can be added to the list? What request must be sent?

Hypermedia RDF

It is easy to understand, given that RDF has evolved to be a flexible data model, that the hypermedia controls are lacking. That is because RDF focuses on defining data structures and their relationships. Hypermedia however is all about behaviour. There are a number of solutions, which intend to form a bridge between RDF and hypermedia, thus making a truly RESTful service:

  1. Linked Data Platform
  2. RESTdesc
  3. Hydra

Each on of these approaches proposes a slightly different approach. Linked data platform is a set of guidelines, which a conforming servers and clients should follow to allow a consistent interaction between them. RESTdesc enables server to embed metadata about hypermedia included in the representation in the form of if..then rules expressed in RDF, which define “what it means to follow a link”. Hydra is similar to RESTdesc in that hypermedia cen be included directly in representations but it also allows building a centralized metadata of possible interactions. Unlike traditional API documetation, Hydra metadata is itself also RDF, which can be queried by the client at runtime to decide what options are available for the next transition.

What next?

In upcoming posts I will try to give a concise example of using Hydra and next I will try to express my ideas for realizing the code-on-demand constraint by combining Hydra and SPIN

Comments