Lead Image © bowie15, 123RF.com

Lead Image © bowie15, 123RF.com

Developing RESTful APIs

Late Bloomer

Article from ADMIN 40/2017
By
The popularity of REST APIs has increased of late, not only on industry sites, but also in the framework of smaller projects. We explain why this is so and illustrate the fairly abstract architectural approach with a concrete example.

Almost 15 years before Tim Berners-Lee and Robert Cailliau started up the first World Wide Web (WWW) server, James E. White published the idea of the Remote Procedure Call (RPC) with Request for Comments (RFC) 707 [1] in 1976. The idea was for an RPC to allow a computer to run a function on a remote computer. Machine-to-machine communication (M2M) thus became real.

In contrast, while developing the HTTP protocol and the hypertext markup language (HTML), Berners-Lee was thinking of human users who navigate globally distributed documents – that is, the man-machine interface.

The main difference between the two architectures is how the client approaches the resources on the server. RPC requires the client to possess very specific knowledge of how to access remote resources on the server. Here, the developer needs to study the protocol specification in detail to understand the meaning of the data elements for input and output.

On the web, however, a visitor is unlikely to read the instructions for a web page before using the service, thanks to the text-based HTML format. Users intuitively conclude how to use a web page from what they see on the page itself. Machines do things differently. In M2M communication, the developer needs to define how the machine interprets the data in the form of specifications.

Back in 2000, Roy T. Fielding, in his highly readable thesis [2], called for a drive to establish the four principles of high scalability, ease of usability, extensibility, and self-descriptive hypermedia as the basis for an efficient web architecture and to implement it consistently in the form of Representational State Transfer (REST).

Machine Talk

The inventors of the WWW quickly realized that humans were not the only ones who could take advantage of the hypermedia world. To avoid the problems inherent in the arbitrary approach of hypermedia, the developers imposed certain restrictions; for example, HTTP was designed to be a stateless protocol, which means the server does not need to worry about which point its clients have currently reached in the workflow. In this way, a server can manage many clients with little effort. At the same time, the protocol is kept very simple; it includes only a few request methods (verbs), such as GET, HEAD, and, depending on the server, the optional POST, PUT, DELETE, OPTIONS, TRACE, and CONNECT [3].

The key to the success of the web was the hypermedia format, which combines application logic and presentation. With the help of HTML interfaces, servers deliver the clients for their own web applications. The HTML format also makes it possible to combine resources so that users can navigate the application interactively and jump from HTML page to HTML page.

These relatively clearly defined constraints and the intuitive logic of the web also should work really well for the machine interface, but in practice, only a few APIs take this into account. Although increasing numbers are using the HTTP protocol, you will usually find a mix of protocol logic and application logic.

Developers also typically need to spend time learning the data format, which is far removed from the self-explanatory HTML navigation through clearly marked resource linking.

REST to the Rescue

Although it has been around for nearly two decades, REST has only seen use in the industry for a few years. One reason is because of the way developers traditionally design APIs. Often, architects define the perspective at too early a stage: The focus could be on the front end, or the database design, or the data format. As a result, the development work produces hard-to-understand and mutually incompatible APIs that sometimes offer very similar functions. REST can help resolve these redundancies and allow a sustainable operating concept.

Fielding sees the key to the REST approach as an additional service layer between components, with a view to making the user perspective independent of the specific technical infrastructure to the extent possible. Abstracting the technology, while taking into account the user's point of view, inevitably simplifies system architecture from the client's perspective. As a result, an external developer can understand more easily how a client communicates with the application.

All told, Fielding thus wants to simplify the system architecture to make the operation and development – not only of the application, but also of thousands of independent clients – efficient and sustainable. Abstraction no longer occurs exclusively at the database (Postgres, MySQL) level and web server (Apache, Nginx) level, but also in the data formats, which are based on standards, conventions, RFCs, and registered media types.

Fielding defines four necessary conditions for REST, as follows:

  • It must uniquely identify relevant resources.
  • It is only allowed to change resources through abstract representations.
  • It provides self-explanatory descriptions.
  • It relies on the hypermedia format, which controls the application state.

Probably because Fielding's description was quite abstract, practical implementation only arrived after a long wait. Only now, after many API developers have gone through the painful experiences that Fielding anticipated, are developers translating his ideas into practice.

Finally Tangible

Today REST – in the context of the web – can be defined as resources, including database entries, images, documents, or other electronic data, that can be addressed via unique Unified Resource Identifiers (URIs) that do not need to be user-readable, and definitely not in a machine-to-machine interface. However, it should be possible to clearly match a URI to a resource.

The developer does not manipulate resources such as database entries directly, because REST first abstracts them in a presentation layer, thus decoupling the data from the database design.

The data formats used here contain both all the information and functions to cover the application logic. Because REST relies on standards, the application behavior follows well-known mechanisms, and the interface more or less describes itself. For example, the method attribute is used in a form; the use of href to link to another resource simply makes sense. Last but not least, HTML, with its well-defined elements, including links and forms, guides the web application from one controlled state to the next.

Buy this article as PDF

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

Buy ADMIN Magazine

SINGLE ISSUES
 
SUBSCRIPTIONS
 
TABLET & SMARTPHONE APPS
Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

  • Haskell framework for the web
    The Yesod web framework includes a Haskell compiler on top of the standard web technologies, such as HTML, JavaScript, and CSS, with aggressive optimization and function checks for correctness.
  • Swagger and OpenAPI Specification for documents
    A REST API is especially useful for a developer if the API provider extensively documents the methods used. The Swagger tools not only semiautomatically generate an API reference, but a matching client SDK for many programming languages, as well.
  • OrientDB document and graph database
    OrientDB is a NoSQL document and graph database with a flexible data model and an elegant approach to querying.
  • A REST interface for FreeIPA
    Access to the FreeIPA identity management framework is usually handled via a graphical web interface or a command-line tool, but the framework can also be queried directly via the JSON-RPC API.
  • RESTful APIs in practice
    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.
comments powered by Disqus