Avatar Software AB

Resource-Oriented Architecture (ROA)

A description of the fundamental concepts underlying the web services on this website.

Web services

Web services are computational resources available on the World Wide Web. The resource may be simple, such as a static XML document for a client program to fetch, parse and use in some calculation. More complex web services are, for instance, sites that perform some type of calculation or that allow a user to modify the contents of a database on the web server.

A more strict interpretation of the concept 'web service' is that it is a web resource that has been designed for programmatic access. It allows software on another machine on the web (the client) to access and use its features in a well-defined manner.

It is often possible to write a program that extracts information from an HTML page intended for human viewing, making that web site a de facto web service. But this is a notoriously brittle solution, and therefore unsatisfactory. What distinguishes a web service from a web site is that it is purposely designed for access by client software.


In bioinformatics, as in many other fields, web services have tended to become equated with technologies such as SOAP, WSDL, UDDI and the many 'WS-*' standards.

However, it is a common misunderstanding that these technologies are necessary to create web services. This is not the case; web services are perfectly possible without the specific technology stack of SOAP et al.

This is fortunate, since there are reasons to believe that the SOAP approach poses high barriers of entry into web services for small and medium-sized organizations. To realize the full potential of programmatic web services, an alternative is needed.


The case for web services designed according to a Resource-Oriented Architecture (ROA) was presented by Leonard Richardson and Sam Ruby in their book RESTful Web Services (2007, O'Reilly Media Inc. ISBN:0-596-52926-0, BookFinder:0596529260, LinkBaton:0596529260).

The fundamental idea is that the basic, well-understood, and well-known technologies of the current web (HTTP, URI and XML) should be used according to their design principles. This facilitates the design of web services that have simple and coherent interfaces, and which are easy to use and maintain. Such web services will also be easier to optimize for working with the existing infrastructure of the web. The design principles of the web technologies are summarized by Roy Fielding's notion of Representational State Transfer (REST) in his Ph.D. thesis Architectural Styles and the Design of Network-based Software Architectures (2000).

The Resource-Oriented Architecture (ROA) consists of four concepts:

  1. Resources
  2. Their names (URIs)
  3. Their representations
  4. The links between them.

and four properties:

  1. Addressability
  2. Statelessness
  3. Connectedness
  4. A uniform interface

The */wr resources of this website have been designed with these concepts and properties in mind. The URIs (only URLs, actually, in the */wr resources) have been designed for clarity and consistency. The representations (HTML and XML) of the resources have a high signal-to-noise ratio. The representations are strongly linked; it is possible to navigate through the representation of all entities just by following links. This is true for both the HTML and XML representations.


One of the most important benefits of ROA is the low barrier of entry. For a small organization (e.g. a small research group) that wants to use web services, either on the client side (using services provided by others), or the server side (exposing their own resources to others), it is essential that the overhead is as small as possible. If many different, special-purpose technologies and standards need to be mastered, then the overhead in terms of time and effort may well become prohibitive. Since ROA uses only the well-known basic technologies of the web, it is likely to be much easier to use than the SOAP approach, which has its own unique and extensive technology stack.

In order to lower the barrier of entry even more, we introduce here the design principle of isomorphic representations. This is the idea that the different representations should be as similar as possible.

In practice, this means that the XML document representation for any given resource should have the same information content, links and basic design as the corresponding HTML document. In addition, the URLs for the different representations should be the same for a given resource, except for a format specifier. This principle can be seen as a variant of WYSIWYG: What you see (in the browser) is what you get (programmatically).

Isomorphic representations allow a potential user to grasp the design of the programmatic web service simply by browsing the human web site. By noting the URLs and looking at the HTML and corresponding XML documents, it becomes much simpler to write a client program to automate the analysis the user has in mind.

The resource perspective

The two concepts 'resource' and 'service' have a duality relationship. A service is needed to create a resource. A resource is required to provide a service. One is impossible without the other, and both are equally valid. However, one of them may be more relevant and useful in a particular context.

We propose that the resource perspective is more useful in the context of web services. Consider an analogy: When a biologist needs a buffer solution to perform an experiment, then what she wants is the resource, i.e. the ready-made solution. Whether she makes it up herself, it is provided by service personnel, or it is purchased from a company is really a secondary issue. Certainly not unimportant, but still secondary!

Similarly, the primary point of bioinformatics web services is not the fact that a service is involved, but that the user (client program) can obtain a certain resource. For example, when a user performs a sequence search using BLAST, it is not the BLASTing per se that is the primary goal of the user, but rather obtaining the list of hits with the scores and alignments. The resource is primary, the service secondary.