Friday, April 17, 2009

A closer look at REST

YaST, the openSUSE installation and configuration tool, is about to get a web based user interface.

The interesting part of this is the proposed service-oriented architecture. REST, Representational State Transfer, is currently the holy grail for managing resources (objects) using http.
REST is not a protocol but an architectural style making best use of the properties of http. And the Internet is the best proof that this style performs and scales well with a distributed client/server architecture.

Roy Fielding, one of the authors of the http protocol, has written a complete doctoral dissertation on this topic. For the purpose of this blog entry, seeing it as a lightweight alternative to e.g. XML-RPC or SOAP is sufficient.

How does it relate to YaST ?

As Stefan has explained on his blog before, a web based YaST will be splitted into client and server parts. This forms a three tiered architecture, where the server runs on the managed system and exposes a REST-style API to access YaST functionality.

Getting this API right in terms of extensibility, flexibility or conformance to REST best practices is an important design goal.

Now whats good REST style ?

There is no fixed list of requirements for REST or a conformance testing tool. Designing a well behaved REST implementation is mostly about learning from others experience and follow common practice.

Browsing through popular REST related bookmarks at gives me a much better signal-to-noise ratio than Google. And it pointed me to a couple of useful references for the do's and dont's when planning a REST-style architecture.

  1. REST APIs must be hypertext-driven
  2. Versioning REST Web Services
  3. Common REST Mistakes
Hypertext style

The first is the most interesting (IMHO). Its about exposing only a very limited set of explicit URIs. This also prevents hard-coding them into the client but let the client query the server instead. So you start from a single URI and hop from there (thats what hypertext is all about!) to the right resource. Thats like moving from node to node in a state diagram.

Versioning in media types

When doing API versioning on the web, one might be tempted to do an all-or-nothing approach and embed a version specifier (like .../v1/...) into the URL. The second link above explains why this is a bad idea and comes up with a better one: media types. The client can tell the server how to format the response to an http request by setting the Accept field in the http header. Its like calling a function and telling it the expected return type.

And REST explicitly supports this style as it does not make any assumption on the representation of a resource. Client and server are free to agree on the actual format. Using XML for object serialization is a smart move as it allows for extensibility. Clients just pick the xml tags they need and ignore all others.


REST, being based on http, stipulates a stateless protocol. Doing stateful REST is listed as one of the typical mistakes in implementing REST-style.
Considering the proposed YaST web architecture, this means keeping state (session) information in the client and not in the server.

More recommended reading