The Pure Doctrine

REST (representational state transfer) is a design principle applied to programming interfaces. Not so much a specific standard, it is rather a collection of guidelines for the design of web interfaces. REST is committed to the consistent use of hypermedia to scale a web service to the max and make it as flexible as possible. In the previous issue, I devoted an article to the theoretical superstructure of REST [1].

Once you have learned the principle, it is easy to familiarize yourself with new REST interfaces. Providers benefit from REST when they propagate open interfaces as soon as possible, thus making them attractive to many developers.

However, a RESTful API requires discipline in its design, which causes some providers to take shortcuts through proprietary formats and function calls. Integrating standards takes time, and not every developer or every company is enthralled with the idea of having to supplement documentation or add abstraction steps, especially as applications become more complex, requiring developers to put more effort into representing each relevant application state via unique URLs.

On Your Marks!

To make sure I compare like with like, I briefly introduce the central concepts of a RESTful API. The crux of a RESTful service is the resource, which can be a file, a database record, a certain application state, or an intermediate step in the program sequence. Rather than passing this resource directly to the interface, the developer accesses a generalized representation of it.

This indirect route via a representation is another important element of REST. The Rails framework and object-oriented programming (OOP) embody this principle. They also collect an additional presentation layer that neatly separates a user perspective and the application logic. From a database entry, Rails makes a model (or an object-oriented program an object) that is aligned more toward application logic and less on the database schema.

Hypermedia combines hypertext and multimedia. REST uses hyperlinks to connect documents, which allows navigation along a planned sequence. Hypermedia therefore allows you to combine resources in such a way that the next step is a result of the information available, thus defining the fourth criterion of a RESTful API.

Get Set!

Because uniform standards for REST do not exist, I reference the design criteria presented in my previous article [1]:

• Unique Uniform Resource Identifiers (URIs) address resources such as database records and application states relevant to the process.
• The developer does not manipulate resources directly but uses a presentation layer that matches the user's perspective.
• The data exchange is based on hypermedia and interactive linking between the application steps.
• The next application step can be anticipated from the information currently available.

A RESTful API that deserves the name needs to implement these four criteria, although they do not guarantee quality in their own right. Even proprietary remote procedure call (RPC) interfaces over HTTP scale well and are easy to use, but they should not be called RESTful if they do not incorporate REST.

Go!

From the list of providers who call their APIs "RESTful," I chose the following three to examine in this article. Two are popular Internet services from Twitter [2] and WordPress [3]. Because of the high number of users and open interfaces, you can expect an affinity with REST. A smaller provider, figo [4], seeks to emulate the online banking interfaces used by banks with REST.

In this article, I introduce the APIs of these services and assess their "RESTfulness," according to the above criteria, with a score ranging from 1 to 3 (Table 1). The rankings indicate how the provider implements the RESTful API.