Lead Image © Michal Bednarek, 123RF.com

Lead Image © Michal Bednarek, 123RF.com

RESTful APIs in practice

The Pure Doctrine

Article from ADMIN 41/2017
Internet providers often market their open interfaces as RESTful, but is this true of the APIs, especially when no standard exists? We introduce some REST providers and look at how closely their API architectures reflect the REST principle.

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.


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.

Table 1

Comparison of REST Interfaces

    Implementation Score*
REST Criterion Twitter WordPress figo
URIs for Resources 3 2 3
Presentation Layer 3 3 3
Hypermedia Data Formats 2 2 1
Self-Explanatory Process 3 2 3
Total 11 9 10
* 1, almost; 2, on average; 3, comprehensively.

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Learn More”>


		<div class=