That's fine and well, but JSON isn't a natural hypermedia and it has struggled to achieve much by adopting hypermedia-like features.
I think this is because the power and flexibility of the hypermedia model requires that the consuming entity have agency, and humans consuming HTML (unlike the code consuming JSON) provide that agency:
Providing more documentation for JSON is an admirable goal, but that isn't the uniform interface of REST, which requires no documentation, just an entry point from which all possible actions are surfaced via hypermedia.
Rather it is better documentation for what is a fundamentally RPC model (not bad! just different)
No format is a hypermedia, because hypermedia involves heterogenous formats bound with links.
But any format in which links can be conveniently embedded can participated well in hypermedia, and JSON is definitely a format in which links can be embedded.
> humans consuming HTML
Humans aren't any more the usual consumers of HTML than they are of JSON. In both cases, software consumes and may (or may not) interact with humans. But immediate agency in the consumer isn't necessary for hypermedia, in fact, the hypermedia model is very much intended for robust mechanical consumption by systems not designed with advance knowledge of the structure, because hypermedia is self-describing.
That's why web mashups, search engines, archives, and specialized crawlers are all able to work.
> JSON is definitely a format in which links can be embedded.
Not really? Html has a way to include links (a/href) json has strings.
One can of course add on top of json (like one can build on utf8 text to build json). But json is a pretty terrible format - quite simple, but quite weak.
You can embed links in json as much as you can embed a json document as a base64 encoded string inside another json document...
Bots can crawl a link graph, but that seems to me to be a relatively primitive use of a uniform interface when compared with a human interacting with a hypermedia system.
I think this is because the power and flexibility of the hypermedia model requires that the consuming entity have agency, and humans consuming HTML (unlike the code consuming JSON) provide that agency:
https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
Providing more documentation for JSON is an admirable goal, but that isn't the uniform interface of REST, which requires no documentation, just an entry point from which all possible actions are surfaced via hypermedia.
Rather it is better documentation for what is a fundamentally RPC model (not bad! just different)