Why You Shouldn't Dismiss Hypermedia in Your API Design

Many modern APIs are built using the REST architecture, and its constraints hold many similarities with HTTP. In a recent post on Medium, Olivier Hervieu discussed these constraints and how few “big” APIs adhere to the use of hypermedia to drive transitions and actions, despite the benefits it offers developers.

As an absolute requirement of the architecture, truly RESTful APIs should respect the “uniform interface” constraint, which includes transitions and actions to be driven by hyperlinks and hypertext, according to the author of the Apache Web server, Roy Fielding. This method is often referred to as Hypermedia as the Engine of Application State, or HATEOAS. This is the same method that is used in classic websites, where clicking on hyperlink text complies with the HATEOAS constraint to perform the intended action and, for example, retrieve the next page.

Applying this method to APIs would drastically simplify many API calls, bringing the system more in line with Fielding’s specifications and standardizing the Web. However, it would also raise a few other issues, such as the need for a comprehensive list of link relations, as well as the larger size of replies with slightly more requests, which would put further strain on existing connectivity issues. There is also the fact that few Web giants provide a hypermedia API, with Google being the only one Hervieu is aware of.

This lack of relation information means answers are often far larger than nonhypermedia responses, but this can still be outweighed by the increased adaptability that comes with providing links in your replies that allow you to change the link destination of your resources. The provided relationships make your responses self-descriptive, and the stable format brings a predictability that will help guide responses. All of this works together to make truly RESTful APIs that are comprehensive, adaptable and more resilient to the changes that are always occurring.

Be sure to read the next API Design article: Why API Description Languages are a Great Choice for Enterprise

Original Article

How your API could benefit from Hypermedia