In a recent article series looking at web APIs, developer and author Steve Klabnik discussed the implementation of hypermedia by using four real-world examples from his own experiences. He began by dismissing the idea that it is all-or-nothing when it comes to incorporating hypermedia in your API.
Server-driven interactions can be used where needed to enhance features without the need to do a full overhaul of your existing API. Twitter’s GET Users/Show API, for example, responds to requests for thumbnail images with links, which qualifies as hypermedia. So instead of including the images inline using a data URI, employing links informs the client of what options are available and where to find them. This increases flexibility and discoverability while reducing the size of the payload.
Hypermedia also has applications in pagination, as used by GitHub in many of their resources. Since different API calls respond with different defaults, for example in the number of items per page when searching GitHub’s different public repositories, using links can drastically reduce issues when these defaults are changed.
Klabnik has used hypermedia himself to get around the restrictions of developing in iOS. Since the server can change the behavior of the client, it allows the app to bypass limitations on things like file size by offering different files from the server once the app has received approval from Apple. Hypermedia also allowed for minor changes to be made to the app without the need for app updates for those changes to take effect.
Hypermedia in APIs does have its downsides, but for the moment those revolve mainly around a lack of understanding. Terms like ‘customer URL’ replacing ‘customer ID’ will cease causing confusion among customers as hypermedia usage grows, which it is certain to do, given its power and versatility.