First presented by Leonard Richardson in 2008, the Richardson Maturity Model has four levels (0 through 3). These levels, particularly Level 2, seem to be more concerned with HTTP-based APIs, whereas the REST architectural style is clearly protocol agnostic, so one could argue that it cannot strictly be applied to all APIs. However, the focus of this article, written by Chamal Nanayakkara, is the final level - Level 3 - which can be applied more broadly.
To be considered Level 3 in the Richardson Maturity Model, an API must provide hypermedia controls in its resource representations, which would enable a client to navigate through the API. This was not a new concept introduced into the model, but was part of the REST architectural style ever since it was first introduced by Roy Fielding in his PhD thesis in 2000. Dr. Fielding has made it quite clear that the inclusion of hypermedia controls is absolutely essential for an API to be considered RESTful. He was quite adamant of this point in a 2008 blog post, when he wrote that ‘... if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API’. The Richardson Maturity Model simply takes this idea and presents it as the final hurdle in developing a RESTful API. This concept is widely referred to by the acronym HATEOAS, which stands for ‘Hypertext As The Engine Of Application State’.
Many developers seem perfectly happy to leave their API at Level 2 in the maturity model, although their API has the capability to distinguish between different resources and uses the properties of the underlying protocol (such as HTTP verbs and response codes) to deal with different types of requests. In order to understand why this happens, we first have to understand what HATEOAS or hypermedia controls are in the context of an API and their purpose. In the simplest terms, this is the inclusion of links in the resource representations (i.e. the payloads a client receives from an API) that enable the client to perform certain actions on that resource or to navigate to related resources. The benefit of this is that the client does not have to have each endpoint of the API hardcoded, and can simply refer to the hypermedia available in a resource and follow that to perform a desired action. This, in turn, allows changes to be made to the API’s URI scheme without fear of breaking any clients. Client developers would not have to refer to separate documentation to find the API routes for each action they need to perform as so often happens, but could simply program the client to follow the hypermedia controls after accessing the entry-point of the API.
In reality, however, the adoption and implementation of HATEOAS is not that simple or straightforward. In fact, there seem to be very few APIs, even from tech giants in the IT industry, that have HATEOAS implemented. The problem, in the author’s opinion, is that there is no single standard for implementing these hypermedia controls and different APIs may use different formats and standards. Formats such as ATOM, HAL, JSON-LD, SIREN are some of the prominent examples. A client consuming such an API must be able to read and follow this hypermedia format in order to make use of it. However, while an organisation may choose a single format and go through with it for all their APIs in their internal usage, other external APIs may use different standards. API client developers will then have to accommodate four different hypermedia formats, at which point they may well be tempted to abandon that and fall back to the old fashioned way of referring to the API documentation and keeping track of each and every API endpoint they need in the client.
Perhaps in turn, API developers may also see little value in spending their efforts to implement a feature that their clients rarely use. Stuck in this cycle, even an otherwise well designed and fully fledged API may not reach the coveted Level 3 of the Richardson Maturity Model, thus never becoming a truly REST API by Dr. Fielding’s definition.
