A hypermedia API embeds navigational links and affordances directly in its responses. Instead of the client needing to know every URL and every valid action ahead of time, the API tells it what it can do next — the way links on a web page guide a human through a site. This is hypermedia as the engine of application state, the constraint at the top of the REST maturity model.
It is the most intellectually compelling idea in API design and the most commercially frustrating. Done right it produces APIs that are more discoverable, more evolvable, and more loosely coupled. And it never achieved the adoption its elegance deserved.
The reason, as best I can tell, is cognitive load. A human developer does not want to follow links and interpret affordances at runtime. They want to read the docs once, hardcode the calls, and get on with their day. Hypermedia asked developers to write more sophisticated clients in exchange for a benefit — evolvability — that pays off later and to somebody else.
Here is the turn I did not fully see coming. An agent navigating an API at runtime is exactly the consumer hypermedia was designed for. Machines can process links and affordances tirelessly and have no objection to discovering what is possible instead of being told. The cognitive-load problem that doomed hypermedia for humans may be precisely the problem hypermedia solves for machines. It may simply have been early.
