[This article was written by John Mueller.]

You have probably used APIs (application programming interfaces) of all sorts when creating applications. It doesn’t matter what the platform is, developers generally have to work with APIs to get any work done because modern applications rely on code that is written by someone else and uses an API for communication. The ultimate goal is to manipulate data in some way and then do something with the result. A problem with APIs is that they leave too much information out, so the developer spends considerable time thinking about how to work with the API and then making mistakes when the interpretation is wrong. Hypermedia APIs solve this problem in a number of ways, but the two methods that developers need to consider immediately are:

• Provides a shared, common method for developers to interact with data.
• Helps developers understand what actions they can perform on the data using the API.

The following sections discuss hypermedia APIs in more detail, but the essential consideration for most developers is that they reduce the time required to learn a new API and to use it productively. In addition, working with hypermedia APIs reduces the risk of mistakes, so that applications are more likely to work well at the outset and remain robust during their useful lifespan.

Defining a Hypermedia API

The basis of a hypermedia API is the registered hypermedia type used to provide the shared, common method of interacting with data. A hypermedia type is defined as a Multipurpose Internet Mail Extensions (MIME) type that contains hyper-linking semantics. It’s the inclusion of hyper-linking that makes it possible to interact with the data without the usual learning process involved with other API types. A number of hypermedia types have been proposed, but not implemented as part of a solution: Atom, CCXML, CSS, Notation 3, RDF/XML, SensorML, Sitemap XML, SMIL, SVG, text/uri-list, TriG, TriX, Turtle, and VoiceXML. However, as a practical matter, you have these choices now:

• Collection+JSON (JavaScript Object Notation)
• HAL (Hypertext Application Language)
• Siren
• XHTML (Extensible Hypertext Markup Language)

When an application makes a request using a hypermedia API, it still receives a result (some type of data) in return. However, in addition to the data, the application also receives a list of links that define what the application can do with the data now that it has it. Having this list of links means that the developer knows precisely how to interact with the data in a manner that is consistent with the originator’s intent. The links also make it possible to interact with the source site without problems. In short, using a hypermedia API makes things simple.

The links are hierarchical. You begin at the top of the hierarchy and work your way down to precisely the data you need. As a result, using a hypermedia API can become verbose, but it’s also incredibly organized. The path to the data you need is always presented as part of the list of links you receive. As a consequence, developers no longer need to grope in the dark to find what they want.

Let’s look at a really simple example. You might need to request information about a part in a catalog. If so, the request may look like this:

In this case, the request is asking for a search of an item with a SKU of 555-ABC. The caller wants to know if there is at least one of these items in stock.

Assuming that the response is successful, the server will follow the normal protocol of repeating your request, providing a response, and also providing a set of links for actions. Here’s what you might see as a response:

The response tells the caller that the internal ID for the item is 156. The item is in stock and the organization has 25 items available.

Now that the caller knows that the item is available, it’s time to do something with the information. Here’s where the <links> element comes into play. Each link tells about an action that the caller can perform with the information supplied. In this case, the caller can order a new item, check on an invoice for an existing item, determine whether payment has been received for a previously ordered item, or return an item to stock. The accompanying links provide the information required to perform the action.

Understanding the Server Side of the Story

Developers aren’t the only ones who benefit from a hypermedia API—it provides benefits at the server end as well. The problem with many APIs today is that they’re rooted in network and desktop patterns that don’t scale well. When working in an older environment, it was possible to predict the load that would be placed on the various elements of an application solution. The Remote Procedure Call (RPC) technique of using functions and returning objects worked in the past, but is increasingly viewed as inflexible and problematic.

Unfortunately, with Web applications, it’s not possible to predict a potential load as easily, so the solution must scale well. Using hypermedia APIs makes it possible to scale the solution so that it continues to run even when the load becomes larger than originally anticipated. With this in mind, hypermedia APIs rely on links that return forms containing the requested data. Essentially, a caller is making a request and receiving a message in return. It’s akin to serving pages to browsers, which fits in nicely with the way other tasks are performed on the Web.

However, the most important thing on the server side is stability. Providing a documented list of activities that a caller can perform means the server spends a great deal less time servicing errant requests and more time managing data. As a result, reliability and stability both increase. The setup is more secure as well because there are fewer opportunities for outsiders for abuse the system.

A Potential Negative

There is an important issue that you need to consider as you begin working with hypermedia APIs. Some sources will tell you that it’s possible to change your URIs for requests because the caller will obtain a fresh list of URIs with each response. The problem is that once a developer has used the API for a while, there is every chance that the developer will want to create application shortcuts by bookmarking URIs, rather than travel through the URI hierarchy every time. With this in mind, some people who work with hypermedia APIs regularly make these recommendations:

• Don’t change the API URLs (adding new URLs as needed is fine)
• Document the API fully so that developers can read about it as needed.
• Provide the required client wrappers so that making calls is easier.

Bottom Line

Hypermedia APIs are the newest thing to come out to make developer’s lives easier. However, they’re still in a state of flux. Unlike more established techniques, hypermedia APIs require more work before you can consider them complete. They’re complete enough to perform useful tasks now, but be prepared for changes in the future. Using hypermedia APIs will save time and effort. They also make both application and server more stable, reliable, and secure.