Through the channel of today’s web API (Application Programming Interface) an ecosystem of internal, partner, and independent developers can access an organisation’s data and services to create use cases beyond what’s imaginable by the organisation itself.

To better support the development of these use cases, it becomes necessary to evolve the API beyond its original design such as updating interfaces or by adding or removing functionality.

But what happens today when an API changes? For many of today’s APIs that use the traditional REST implementation, there is a tight coupling between API provider and consumer where the client hardcodes the API’s URL web address, and the input and output formats. Then changes made to the API must propagate to the multitude of apps through reprogramming of the calls and formats, otherwise something will break and malfunction.

As use cases increase, it is not feasible due to scale to coordinate API changes by reprogramming all the clients. Instead, a hypermedia API architectural model allows clients to discover and adapt to API changes themselves. The provider crafts an API response that in addition to the requested data also contains links to other allowable actions and related data; then the client dynamically discovers these up-to-date capabilities and interfaces each time it queries for an API response.

This response includes the usual data part of a traditional REST API response and in addition, related resource links as part of the hypermedia model. Here the link is to the query for the full listing of movies where “ht:movieList_category” is short form for “”. The details describe the metadata needed for the client to retrieve and interpret a query for all movies related to the “Musical” category: i.e. language, name of the resources, and display title. Finally the “self” link tells the client the original location of the response data.

Through the links, the API provider guides the client on allowable next steps. By updating the links section, the provider can introduce new actions: like links for adding data through an operation to create a new movie category like Drama or Horror. Including the possible next steps along with the links to execute them in the hypermedia response gives the API provider the flexibility to change those actions and links at the provider’s discretion.

Taking advantage of these added details in the hypermedia response assumes that the client can adapt and follow the direction. But even without this client ability, the live nature of the hypermedia API response allows developers to better understand the API’s capabilities through exploring the API links rather than through documentation that can easily fall out of date.

In the case of the movies example, the root response may include a link “/category” for pulling the top level movie categories. The hypermedia client does not hardcode the links but reads it at runtime so it can adapt to change. For example, a change in the naming of an endpoint from “/category” to “/genre” will gracefully propagate as the client simply follows the appropriate link.

The client discovers the offered operations and any updates through navigation of the API. The client lists the categories and URL links contained in the response to the call for “/genre” rather than hardcoding based on previous knowledge of the categories. So if the provider adds a new category “Comedy” or removes “Musical,” then call for “/genre” will return an updated set of URL links that propagates to the client.

For example, if a provider deprecates a resource class by removing the resource link from the API response. A hypermedia-aware client learns the missing resource from the response content and notifies the client developer.

The hypermedia API architectural style is not new and is part of the original definition of REST. But this discoverability aspect has been long overlooked and underutilised - maybe because organisations were focused heavily on just having APIs without too much planning for long-term scalable evolution. Or because many initial APIs were data APIs without clear next steps and hypermedia better suits cases in propagating updates in process direction between the API provider and client.

Regardless the reason, today’s proliferation of API use cases means that propagating API changes through direct notification and client reprogramming necessitates the adoption of a hypermedia model to support system evolution.

Hypermedia APIs provide long term business value by minimising cost of provider-client evolution in scenarios where the number of clients is so big that the collective cost of evolving each client is expensive. Today’s challenge is to convince those starting with APIs to adopt hypermedia early in their journey. What seems like a lot of initial complexity, especially for the client, provides maintainability and allows an API program to evolve.

Accenture API image.jpg

Posted by Abiel Wold, Researcher, Accenture Technology Labs, and Teresa Tung, Senior Manager, Accenture Technology Labs