11436 SSO

API Design: Harnessing HATEOAS, Part 2

Brian Mulloy
Jul 03, 2013

In Part 1 of this discussion, we looked at questions people have in regard to HATEOAS. Now let’s examine how API crafters can revise their API so that it is truly RESTful. Because this is an introduction, we’ll avoid going into detail. Instead, we’ll assert the key point upfront: pure REST APIs require hypermedia clients.

From the perspective of pure REST, if an API is HATEOAS compliant then the client app must also be HATEOAS compliant

In this example, the API developer crafts a system of interrelated resources (state diagrams) and puts them on an API server. The REST interface guarantees that hypermedia is the engine of application state. The client that understands how to traverse a RESTful API will also adhere to the HATEOAS constraint of REST. As usual, the user decides where to click (i.e., what state transition to select).

Tools like API Consoles allow app developers to explore and test API requests and responses to determine state transitions. API Consoles are unique because the app developer is actually acting like an app user.

According to an idea from Elastic Path, when things are working well in a hypermedia constraint API you can randomize all of the URLs. For example, you could Base32 encode all of your URLs without seeing them and be 100% compliant with the hypermedia constraint. In contrast, most popular web APIs today take great pains to make the URLs readable for app developers.

In Harnessing HATEOAS, Part 1, we focused on UI based apps but there are interesting non-UI apps that are compliant with the hypermedia constraint.

“ However, the style does not assume that all applications are browsers. In fact, the application details are hidden from the server by the generic connector interface, and thus a user agent could equally be an automated robot performing information retrieval for an indexing service, a personal agent looking for data that matches certain criteria, or a maintenance spider busy patrolling the information for broken references or modified content.”
~Roy Fielding, Chapter 5, Architectural Styles and the Design of Network-based Software Architectures

The key, across all of our HATEOAS use cases, is that the hypermedia returned from the server drives the app state. This means that when you have a HATEOAS compliant API, you must include all possible links in your responses.

Teams that are considering enforcing HATEOAS in their APIs must be very clear about its anticipated benefits. One of the keys to applying the hypermedia constraint is in understanding that the client’s state is driven by the server and not the other way around. There are use cases where hypermedia is the engine of application state but, in my experience, these use cases do not include the mainstream, mobile app-powered APIs that are common today.

In our next post, we’ll explore a new framework for today’s mainstream, mobile app-powered APIs.

To join the conversation around APIs, check out the API Craft Google Group and the IRC Channel #api-craft on freenode. We'd love to get your feedback and perspective.

For further reading, see:

A special thanks to the api-craft Google group, who helped pull this content together.

Scaling Microservices