Follow Us

We use cookies to provide you with a better experience. If you continue to use this site, we'll assume you're happy with this. Alternatively, click here to find out how to manage these cookies

hide cookie message

Blogs

Views from the Lab

Accenture Technology Labs Staff

API Evolution through Hypermedia APIs

Article comments

Hypermedia APIs provide long term business value by minimising cost of provider-client evolution

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 “http://multimedia.com/rels/movieList_category”. 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


Share:

More from Techworld

More relevant IT news

Comments

Send to a friend

Email this article to a friend or colleague:

PLEASE NOTE: Your name is used only to let the recipient know who sent the story, and in case of transmission error. Both your name and the recipient's name and address will not be used for any other purpose.

Techworld White Papers

Choose – and Choose Wisely – the Right MSP for Your SMB

End users need a technology partner that provides transparency, enables productivity, delivers...

Download Whitepaper

10 Effective Habits of Indispensable IT Departments

It’s no secret that responsibilities are growing while budgets continue to shrink. Download this...

Download Whitepaper

Gartner Magic Quadrant for Enterprise Information Archiving

Enterprise information archiving is contributing to organisational needs for e-discovery and...

Download Whitepaper

Advancing the state of virtualised backups

Dell Software’s vRanger is a veteran of the virtualisation specific backup market. It was the...

Download Whitepaper

Techworld UK - Technology - Business

Innovation, productivity, agility and profit

Watch this on demand webinar which explores IT innovation, managed print services and business agility.

Techworld Mobile Site

Access Techworld's content on the move

Get the latest news, product reviews and downloads on your mobile device with Techworld's mobile site.

Find out more...

From Wow to How : Making mobile and cloud work for you

On demand Biztech Briefing - Learn how to effectively deliver mobile work styles and cloud services together.

Watch now...

Site Map

* *