RESTistential Crisis over Hypermedia APIs

Software developer Evan Cordell initiated a debate about how the hypermedia constraint of REST is at odds with common web APIs requirements in the API-Craft mailing list a few weeks ago.

In discussing his "RESTistential crisis", Cordell noted that the REST style has finally started to reveal its best hidden secret, the hypermedia constraint, after years of debates and practice. While perfectly adapted to human-driven interaction as demonstrated by the Web, there appears to be growing concerns within the web API community about its usefulness for programmable web APIs in general.

He started the conversation with a description of REST and hypermedia limitations when applied to domain-specific web APIs, then considers the need for alternate architecture styles, taking the best of REST but replacing some constraints to obtain different benefits, such as efficient and reliable machine-to-machine communication.

The main concerns cited mention the various ways to deal with changes of an interface over a long period of time. The first solution requires running several API versions in parallel and even several orchestration APIs dedicated to specific client experiences as illustrated by Netflix. Its flexibility comes with significant design and operation challenges.

The second solution requires putting much more effort upfront by designing a RESTful hypermedia API that would more easily cope with changes, limiting the impact on the clients, in a way similar to how HTML browsers and servers work and evolve. But some participants, especially web engineer Mike Kelly, voice concerns about the complexity involved and additional burden on API consumers.

Here is a summary of the conversation including large excerpts of Evan's initial message including section titles:

1) A good API doesn't change

• Thinking about Joshua Bloch's experience regarding the design of public Java API, it seems valid to say that the same rules apply for programmable web APIs.
• APIs are interfaces, following the facade pattern, that shouldn't change on the surface for clients. However, multiple or evolving implementations including the runtime data can be exposed, without requiring the API contract itself to change.

2) Versioning doesn't work

A "Web API" exposes far more than a "traditional" API. It exposes data, and more often than not it exposes the current state of a large set of constantly-changing data. How can you effectively version when your domain model has two versions, which share some subset of data, but are accessed in different ways? You force the clients to break.

• Hypermedia can help an API being less fragile and evolve, but if the data and domain model fundamentally changes. Clients won't be able to automatically adapt to all those change without human intervention from a developer.

3) Hypermedia destroys resource location

• REST prevents fixed URIs and any prior knowledge from clients about the server resources. In practice clients remember URIs (e.g. bookmarks) and servers need to deal with evolution of their URI space (redirections).
• Hypermedia can't isolate the API providers from the laziness of API users who will not follow the proper hypermedia flow but instead will directly target specific resources and URIs.
• As hypermedia APIs tend to be very complex to understand and consume, developers will inevitably optimize their clients and take short-cuts, defeating the whole point of isolating clients from API changes.

4) Hypermedia make sense for human users, not machines

• Machines don't deal well with change over time but humans are very good at interpreting changes and deciding what they want to do next. Hypermedia is very natural to humans, much less so to machine.
• Changes in the domain model require changes in the way it is consumed by clients, hypermedia doesn't buy you anything special here.

A true REST/hypermedia client is really a form of HCI, rather than an API (an AHI - Application Human Interface, if you will)

5) What's so bad about out-of-band?

• Does an API really need to be inherently discoverable?
• Why should the API be self documenting, when the format of the API responses are difficult to read at high levels of complexity?
• Nicely structured HTML, rendered by a browser, with interactive examples and articulate descriptions is easier to read.

6) Are hypermedia APIs really that different from a WADL?

What's so different about a discoverable, hypermedia API? A "HAPI" just seems like an API with the WADL distributed throughout. You still have to start with a single endpoint, and you still have to figure out what you can with the API based on that response.

• Something has to have a description of the domain models, and that's something that will change over time.

7) A Web analogue

• REST in native mobile apps would require Android ML and iOSML languages with code on demand.
• Use of domain specific hypermedia media types still requires you to write custom client code that understands this domain.

8) What seems to really be good about REST

• Beside hypermedia and the Web of documents, REST:
  • enforces a stateless server, making it very easy to scale
  • encourages decoupling of information via resources

The basics are so simple that you can talk to servers in a semantically meaningful way with nothing but the http library included on every platform and language.

The above summary contains several excerpts from the participants, especially Evan Cordell, and also Mike Amundsen, Jorn Wildt and Mike Kelly among others. As a disclaimer, note that I also participated in the beginning of the conversation.

Based on your own experience do you think we need to better differentiate the REST and the web API architecture styles, as well as between human-driven hypermedia and machine-to-machine communication use cases?