Originally published at:http://www.apiful.io/intro/2016/09/27/hypermedia.html

When talking or writing about my research, I typically use the term web APIs and avoid the term REST APIs. The reason is that many APIs to not fully comply with the constraints required by the REST architectural style - specifically, most do not use hypermedia as the engine of application state (HATEOAS), which is one of REST's sub constraint regarding a uniform interface (read REST's creator Roy Fielding emphasizing this constraint). In the last two years researching APIs, I did, honestly though, barely think about hypermedia. My visit at the WS-REST workshop this summer as part of the ICWE conference changed that. I met researchers advocating the advantages of hypermedia, leading to some interesting discussions. Since the workshop, I took some time to reflect on the topic and read up different opinions. This post is a summary of my current thinking on the matter.

The HATEOAS constraint

The HATEOAS constraint requires resource representations to use hyperlinks (sometimes denoted as relations) to indicate the possible next actions clients can perform. In the following, I will address some of the implications of using hypermedia.

Hypermedia as API documentation

If an API uses hypermedia, it may expose only a small set of predefined entry-points, possibly only one. Humans may control clients to follow the proposed next actions and thus iteratively explore the whole API. As some claim, this releases the need to read through HTML documentations or consulting API specifications - Roy Fielding himself denotes it a failure if such "out-of-band information" drives the interaction with an API. However, as a developer, I typically want to obtain an overview of an API's overall capabilities, ideally by seeing a compact summary of all possible interactions. I find it hard to keep the iteratively revealed possibilities in mind and having to mentally paint the complete picture of an API. Also, depending on how I choose to follow the relations exposed by the API, I might miss possible actions or at least have a hard time to obtain complete coverage of the API. As I assess multiple APIs, I do not necessarily want to have to interact with them. Many APIs have access controls and I am hesitant to have to create credentials only for exploration purposes. Finally, documentation typically provides human-readable descriptions of actions and data in-place, which is essential to understand an API. To me, thus, while hypermedia may play a part in documenting an API, it needs to be accompanied by additional, developer-targeted documentation.

Reacting to API changes

Another capability postulated by hypermedia is that changes to an API can be discovered and reacted to by ("smart") clients dynamically, basically automating the evolution of clients as the API changes. If, for example, the URL of a resource changes, clients automatically adapt as they follow exposed relations rather than relying on hard-coded "URL templates" to determine possible API requests. Ideally, the client continues to work in light of API changes - no downtimes and no code changes needed. The challenge of how to deal with API changes is indeed important for API clients. Consider the recent problems caused by changes to the Instagram API. Or, consider recent research that finds that mobile applications overall handle changes to web APIs they consume badly, leading to errors or even the applications to crash.

My assessment of how hypermedia can help to reduce negative impacts of API changes on clients is torn, especially assuming clients are applications that not only need to invoke an API but also need to do something with returned resources (e.g., use them to display information in UIs). On the one hand, if changes would only require to update an URL, automatic adaption of clients seems feasible and desirable to me. On the other hand, when it comes to changes in an API's resource representation or functionality, I am more skeptical. Additional data fields could just be ignored by clients (especially if they are implemented in dynamic languages). Re-naming data fields may be manageable for hypermedia-aware client implementations. However, when it comes to replacing data fields with semantically related ones or even removing data fields, I don't (currently) consider automatic adaptation for clients feasible. Requests against the API may continue to work, but other parts of the client will likely not - required adaptations may include changing database schemes, or updating UI logic. You can always come up with examples where automatic reaction to changes works - but is that sufficient to rely on clients to adapt automatically if there is a chance that things may break? I believe most application developers don't think so.

In discussions about hypermedia APIs, you can read arguments asking (rhetorically) whether developers believe its a good idea to having to replace URLs in source code upon API changes. The web is often used as an example: the browser consumes any HTML page and users follow along links. But when accessing resources programmatically, I'd argue, having to manually react to changes in an API may not be a bad thing. First, you can (and should) organize your code in a way that makes such changes atomic and easy to perform anyhow. Second, API changes typically exist for a reason - they reflect changed API functionality, e.g., different data being returned. As an API consumer, I want to make a deliberate decision about the implications of such changes. Maybe they require me to rethink how I consume an API or if I should still consume it altogether. In the web analogy, ultimately, its also the human that decides about which link to click on. I don't think programmatic clients are yet smart enough to be trusted with that decision.

Adopting new capabilities

Beyond changes to URLs or data representations, hypermedia is also said to enable clients to dynamically adapt their behavior APIs expose new capabilities.

However, clients frequently interact only with a (small) subset of the capabilities exposed by an API, selected, for example, based on user requirements. Such clients, arguably, have no intention to adopt new capabilities, especially when they are the result of API changes rather than user requirements. Consider the case where a client and an API are under control of different organizations: Would the organization offering a client (e.g., a mobile application for editing pictures) really want the provider of an API (e.g., Instagram) to have control over application functionality? Likely not. To me, automatic adoption of new capabilities exposed by an API is a exceptional use case at best.

Tooling support

Implementing APIs that expose hypermedia, ideally, is supported by tooling. Popular frameworks for building APIs in different programming languages, however, lack such support. Express in Node.js, JAX-RS in Java, Rails in Ruby, Laravel in PHP, or the Play framework in Scala/Java - none of them provide capabilities for building hypermedia APIs out of the box (though plugins / extensions exist in some cases).

Quo vadis, Hypermedia?

After considering the scenarios in which hypermedia could benefit API clients, I remain very skeptical of its proclaimed advantages - at least for now. I don't believe it adds much to help developers understand an API, I don't believe that clients in general can or should automatically adopt to changing, dynamically exposed actions, and I believe that hypermedia can only in select cases (e.g., when an API and its client belong to the same organization) and to a limited degree (e.g., when a URL-template changes) help to deal with API changes. Claims that HATEOAS provides a more up to date view on the capabilities of an API as compared to "static" documentations like the OpenAPI Specification are not necessarily true, given the latter may be created dynamically and can be closely in sync with implementations. On the other hand, hypermedia needs to be implemented (with lack of major tooling providers) and increases the payload to be sent in requests.

A large-scale study of real-life API data presented at ICWE this year shows that hypermedia is found to be used in only around 5% of the identified APIs. It thus seems that majority of developers, possibly for reasons different from the ones I stated here, share my skepticism.

Overall, I think there are many compelling ideas behind hypermedia APIs. Maybe at some point applications can be written in a way so that automatic adaption in reaction to changes or as APIs offer new capabilities can be performed automatically, without the risk of undesired side-effects. Maybe these developments will also happen completely independent of REST, if techniques like GraphQL gain traction, which promote the idea of a single endpoint and client-defined "resources". I am happy to continuously reconsider the here stated position.

Until then, I will just keep avoiding the term REST APIs. And I am very interested in your thoughts on the topic!