Fundamentally, people do two things on the internet:

1. Click links
2. Fill out forms

Hypermedia API's are systems which want a consuming API (the programmed client) to do that as well.

Hypermedia API's accomplish this by responding to requests with both the requested data AND other resources available or actions to take.

Example: Pagination

An API for a blog might return a list of the 10 most recent articles. The same response for a Hypermedia API may return both the 10 most recent articles, and links for "Next Page" and "Last Page".

This allows your API client to "learn" those links programmatically, and never have to assume those links via hard-coding of URLs or parameters.

Example: Search

Now imagine the same blog API allows you to search for articles.

An API may give you documentation on what URL to use and how to pass in a search parameter.

A hypermedia API would give you a search form in a response, telling your API client what URL to use, which HTTP verb is appropriate, and what parameters to supply.

Hypermedia API's are websites.

A hypermedia API wants your consuming client to surf an API, like a human surfs the web: Follow links, submit forms.

A hypermedia API provides the information, so if any URL's, actions, or needed parameters change, the consumers (API clients) can still work without being re-coded.

Developers won't follow documentation to find which URLs and what parameters to use for a hypermedia API. They'll follow documentation to learn how they can write their API client to follow provided links and submit provided forms.

How do you pass this information?

There is a tool which has everything needed for such a system: HTML. Yep, a hypermedia API brings you back to generating and parsing HTML. The internet just went full circle (to Roy Fielding's original vision, in fact).

While JSON is not as verbose as HTML, you can still use it to create a Hypermedia API. HAL is one such standard which defines how to accomplish this.