ROA for newbies

CC BY-SACC 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.

Web APIs are becoming in a “de facto” operating system. By using these abstractions developers populate Internet with m2m services i.e. with new APIs. The main criteria of this process are mainly usability, fostering the service integration or creation mash-ups. However there exists some theoretical framework backing this phenomenon: Resource Oriented Architecture (ROA).

In this post I review 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. In this post, some basic concepts and principles will be presented, letting some design clues for the followings.

ROA Architecture

From the technological point of view, there are many definitions of architecture. However it is very interesting the definition included in the book:

“ROA is a way of turning a problem into a RESTful web service i.e. an arrangement of URIs, HTTP and XMLs […]”

Therefore, by using web technologies such as resources, names, representations and methods, it will be addressed the ROA principles. These are the followings:
  • Addressability
  • Statelessness
  • Connectedness
  • Uniform interface
Web Fundamentals

But before that, it is needed to clarify the technological terms used in the description of the architecture. Let us start with the definitions: a resource is an object of the domain of the problem or the solution; in the authors’ words: “It is anything that is important enough to be referenced”. But what does it make a resource “real”? In the web domain, the answer is an URI i.e. a universal resource identifiers.  An URI is just a name allowing the developer find resources in Internet (See Architecture of the World Wide Web and URI – Axioms of Web Architecture). In addition to the formal definition, the URIs usage should adopt some good practice guidelines. Concerning to the URI/resource mapping, taking into account that it is just a name server, it states that a) One URI cannot reference two different resources b) Two URIs can reference the same resource c) Every resource has to have at least one URI; i.e. mathematically, the URI/resource mapping is a surjective function.

The second property of the URI/resource mapping (multiple URI reference to the same resource, can introduce some benefits. For instance sometime you need to use different URIs for the same resource due to different representations. However, it introduces some drawback as well because it makes more difficult to validate the first property.  In the book, the authors recommend to define canonical and non-canonical URIs and to use HTTP 303 response to deliver non-canonical URIs.
ROA principles

There exist four principles of the resources oriented architectures: addressability, statelessness, connectedness and the uniform interfaces.


Again extracted from the book, “an addressable application exposes a URI for every piece of information it might serve”. This means that every resource in the system has its URI. Don’t forget if a resource doesn’t have a URI it doesn’t exist!


This means that every HTTP request contains not just the resource id itself but its state as well. The direct implication of this assertion is that in a ROA paradigm the state model of the system is represented like a URI. So far, these kinds of systems represent data and state using URI. As it will be shown, the uniform interface allows the developers to reflect the dynamic (or interaction) model as well.

Considering the former protocols of Internet, someone could think that this approach is better or worse. As always the statelessness property has some benefits: HTTP requests/responses are simpler, failure management is easier, scalability and distributions are simpler and from the client point of view, the URIs can be seeing as a state flow shortcut.

Worth to mention, ROA is statelessness from the point of view of the client i.e. the server doesn’t know / doesn’t care about the client (or application) state. Nonetheless every resource has its own state and the server has to care about them.


Connectedness is the essence of the hypermedia i.e. of the Web. In words of Roy Fielding: “hypermedia as the engine of application state”. This property of ROA means that the resource representation contains link to other resources. This sequence of links implements logical transitions between different states and, in some way, it is recommended path of transitions. Obviously, if the resources in the system are all addressable this “recommended path” is not mandatory i.e. the web client can follow alternatives transitions between resource states, modify the initial path and create an improved version of it.

Uniform Interface

In the resource oriented architecture, there are only a small set of operations a developer can do to a resource. This reduces the complexity of the systems in term of syntax and semantic. Obviously, the client’s implementation will be affected, becoming in some cases more complex. The basic operations are: read, create, write and delete. These operations are provided for the following HTTP methods:
  • Read: HTTP GET
  • Create:
  • HTTP PUT, to a new URIs
    • HTTP POST to an existing URI
  • Write: HTTP PUT to an existing URI
  • Delete: HTTP DELETE
In addition to these, there are two additional HTTP methods, HTTP HEAD and HTTP OPTIONS which allowing developers to ask for resource metadata and server support, although unfortunately, there are some divergences in the usage.
Some clarifications: the main difference between PUT and POST appears naming the URIs. If the client decides the URI of the new resource, the method should be PUT. The POST method means that the server is in charge of setting the name of the new URI.

In addition, sometimes the POST method is used to implement a RPC-style interface. In this scenario, the client uses the POST method to send a chunk of raw data to the server. The server has to inspect inside the http request to decide the semathic of the petition.

Nonetheless, when a uniform interface is used, the architecture has some interesting properties: GET and HEAD are safe methods and GET, HEAD, PUT and DELETE are idempotent methods.  These properties "let the client make reliable HTTP request over an unreliable network".


After this short introduction, for sure you have found many very well-known ideas and concept coming from Web programming and Internet. Coming very soon, some tips about how to design RESTful web services.