ROA design clues

CC By-SA © 2011 Andrés Leonardo Martínez Ortiz. Some rights are reserved. This document is distributed under the ”Attributions-ShareAlike 3.0” Creative Commons License available here.

In this post I continue with the review of one of the classical references about this topic, the book “RESTful Web Services” by L. Richardson & S. Ruby (O’Reilly 2007). Even though it could be considered an old reference and even the authors recognize that the ROA term could be controversial, for lots developers this books is the first step in the path of web programming. Additional post will follow this one.

In term of ROA concepts, design web services means turning requirements into resources specifications. From those specifications, a "real" web services can be implemented in whatever programming language and deployed in a web server.

The "Restful web service" reference proposes the following methodology:

• Figure out the web service data set.
• Split the data set into resources, defining:
• the name of the resources with URI.
• the subset of method of the uniform interface for those resources.
• representations accepted from and server to the client.
• hypermedia links between resources.
• Interactions and error (dynamic) between client and server.

Defining the data set

In this post, I won't go through the detailed process. I suggest you to take a look of the reference, because there the author use an example to guide you al the long the process.
Once you have your data set take into account that there are three different categories of resources.

• Predefined one-off resources: this kind of resources will use for main aspect of the service, include top-level directories. Most services define few o even no one-off resources.
• Resource bound to data set objects: this objects, potentially infinite, are exposed through the web service, represented with resources.
• Resources represented the results of algorithm:   these kind of resources incudes the results of queries and again there is potentially infinite number of these resources.

Resource naming

The basic rules for URI design are

• Use path variables to encode hierarchy. Path variables are the best way to organize scoping information that can be arranged hierarchically.
• Put punctuation characters (colon, semi colon, comas,..) in path variables to avoid implying hierarchy where none exist.
• Use query variable to imply inputs into an algorithm. Some times this is a little bit tricky, so probably the best is to double check when a user query variable is used.

In this point, it is interesting to pay attention to the length of the URIs. Using the rules cited before, you could get very very long URIs. Although in this moments it seems to be easily managed by client and server, still it could be source of problems, specially for URIs  auto generated.

Design the resource representation

Once you have designed the datasets and the resource names, it is time to concrete what information is sent when the client doing a request of a resource and in which data format i.e. the resources representation has to be defined. It is needed to bear in mind the main aims of the resource representation:

• to convey the state of the resources.
• to content links to additional resources and states. About these, the L. Richarson & S. Ruby comments "[the links included in the representations] are the levers of the application state. If a resource can be modified with PUT, or it can spawn new resources in response to POST, its representation ought to also expose the  levers of resource state".

Hypermedia implementation

Independently of other consideration, the service has to be connected i.e. the client (human or machine) has to be able to find any resource following a logical path of links. Therefore, in this stage, the designer has to verify that everything is ok. In the case of dynamic content (such as searches), the service defines the accessible URL, asking to the client for the criteria, usually using forms.

ACKs & Errors

In this point, we are almost at the end of the design process. However, it is very important define the following elements:

• Right petitions:
• Answers: usually "200/OK" but some times also "304/Not modified" or "303/See other".
  
• Headers: mainly "Content-Type"
• Wrong petitions: responses 3xx, 4xx, 5xx. The only consideration about these petitions and responses is to try being as helpful as possible. So please avoid general responses such as "404/Not Found" if the service is able to provide additional information.

And that is all.
Obviously, you should take a look of the recommended reference and to try programming some examples.
In any case, in a few weeks you will have the next entry about ROA in this blog.