Follow Us

Views from the Lab

API Evolution through Hypermedia APIs

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

Tags: accenture, api, applications, hypermedia

RSSSubscribe to this blog

More from Techworld

More relevant IT news

Contact Us

For editorial queries:
Mike Simons

For website issues:

For commercial queries
Russell Kearney

For more contact details click here.

Email this to a friend

* indicates mandatory field

Techworld White Papers

Optimising data protection for virtual environments

VM environments require the same level of data protection as does the physical server environment. Companies may use data protection tools built for the physical environment in the virtual world, but this has serious disadvantages.

Download Whitepaper

PCI Compliance: Are UK businesses ready?

Exploring the results of a recent survey, including: ? Levels of understanding of the standard ? Current perceptions of actual compliance status ? Attitudes toward addressing compliance

Download Whitepaper

Mobility Management for Dummies

Your complete guide to managing and securing mobile devices such as laptops and smartphones.

Download Whitepaper

Magic Quadrant for midrange and high-end NAS solutions

It is difficult to find one midrange or high-end NAS product that can cater to all needs. File systems embedded in NAS are often designed to solve one major pain point, with additional features being added later to broaden use cases and benefits.

Download Whitepaper

Techworld UK - Technology - Business

Oracle Video

Enabling agile and intelligent businesses

 Changing markets, competitive pressures and evolving customer needs are placing increasing pressure on IT to deliver greater flexibility and speed. Explore truly flexible SOA foundations with this Oracle video.

COLT White Paper

IT Misuse Survey

Complete this survey and you could win a Nexus One

Techworld are running a short survey to discover how UK businesses are managing Internet and email misuse in the Enterprise.

Complete Survey

Complete our survey and you could win a Sony E-book Reader.
Techworld have teamed up with HP to compile a survey relating to server virtualisation. Complete the short survey and you could be the lucky winner of a Sony E-book reader.

Complete the survey here

Site Map