I designed a REST API with a "well-documented" HATEOAS representation (collection+json). The primary requirement was to ensure there was no caller-side language dependency because we had multiple teams that would be calling the API and those teams might use the command line, Python, Ruby, Javascript, etc clients to consume the API results.

API adoption was low in the end - teams in the end wanted libraries rather than a well-defined representation with embedded hyperlinks. Every consumer I heard about simply parsed the JSON bits they wanted from responses and hard-coded URL links in their client apps.

I enjoyed the design and writing of the app - I used Clojure and the liberator library. Probably a wasted effort of engineering in the end. Totally fun project to implement though.

> Every consumer I heard about simply parsed the JSON bits they wanted from responses and hard-coded URL links in their client apps

Exactly. HATEOAS is for humans:

https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

So far I have not experienced HATEOAS deliver value over a wiki with good documentation - that seems like better effort.

> I have never seen how does HATEOAS deliver benefit over a wiki with good documentation - that seems like better effort.

Have you used a web browser? Do you see how it handles known content types from a new website that you haven't previously visited seamlessly without you reading docs and telling it what to do with it?

That is exactly HATEOAS.

In general, understanding REST is often easiest if you think about what browsers do, since REST is the key principal underlying the design of HTTP/1.1 and was largely a rationalization of the evolved behavior of the web per-HTTP/1.1.

> Have you used a web browser? Do you see how it handles known content types from a new website that you haven't previously visited seamlessly without you reading docs and telling it what to do with it?

I want to get my job done with an API, not browse it. I spend most of my time figuring out what order endpoints need to be called in and what data they need to be passed, not what the endpoints are.

The shittiest HTTP APIs I've used had full lists of endpoints but nonexistent documentation of arguments. If HATEOAS solves that I can get behind it, but I don't think it does.

I am a fan of GraphQL, but what evidence do you have for "REST sans a hypertext was always a mistake"?

REST requires a uniform interface. Hypertext (or media) is that uniform interface. JSON isn't a hypertext.

Therefore JSON isn't an appropriate transport for a REST-ful API.

I understand that 99% of the internet disagrees with me.

Could you define your terms?

Especially:

  * uniform interface
  * hypertext

And even more especially how JSON does not meet the requirements?

Uniform interface: https://en.wikipedia.org/wiki/Representational_state_transfe...

Hypertext: https://en.wikipedia.org/wiki/Hypertext

JSON is obviously not a native hypertext, any more than plain text or CSV is. You can, of course, embed URLs in it (or any other format) and call it a hypertext. That's usually pointless, as the links will be consumed by code (rather than a human, in the canonical HTML->browser interaction) so if the URLs aren't simply ignored, they will be dealt with generically.

I wrote about this in HATEOAS is for humans:

https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

Curious to me is that it seems you argue that XML is a valid hypertext; but, isn't it possible to implement most any valid xml document as a json document, even considering attributes?

And, have you seen Github's API implementation? They have the links and self-referential details in their particular json schemas that you seem to imply are necessary and unique for that.

If the argument is that json can't be rendered, isn't it arguable that xml equally has that problem, we just have a program with a common syntax reader format that renders pages equivalently, and something equivalent could be written for a particular json schema?

I do not think that XML is a hypertext. So I agree with you.

HTML is a hypertext.

Yes, Github probably has one of the most as-REST-like-as-possible JSON apis, and it's mostly wasted effort. It would be just as usable, as an API, without all that stuff, since it is consumed by code, not a browser/human.

What does HTML have that XML doesn't have? Isn't XML a superset of HTML?

Maybe the following links can help in understanding hypertext/hypermedia?

http://amundsen.com/hypermedia/hfactor/

https://gtramontina.com/h-factors/

It has a hypermedia spec:

https://www.w3.org/TR/html4/

And a bunch of things called "browsers" that implement that spec. More or less.

I mean, come to that, aren't XML and HTML both just text? Isn't text, then, a hypertext? One can embed URLs in text, after all...

Does this mean that your argument that json can't be a hypertext is because it doesn't already have a universal hypermedia spec?

The language here is getting a little squirrly. "Can't be a hypertext" is too restrictive. "Isn't a hypertext" is how I would say it.

JSON as JSON isn't a hypertext in the same way that XML as XML isn't a hypertext. XHTML is a hypertext based on XML. (HTML itself isn't proper XML.)

There are hypertext specs based on JSON, such as: https://json-schema.org/draft-04/json-schema-hypermedia.html

But, without clients that treat the data as a uniform interface, it's all mostly pointless, which is why most JSON APIs stop at Level 2 of the Richardson Maturity Model, and why things like GraphQL are becoming more and more popular.

In the original model of the web (which is what Fielding was describing w/ REST) where HTML was being delivered to a browser, the uniform interface works: a browser has no idea what the HTML document means but can render it to a form that the human looking at it can make sense of.

Thank you for clarifying your stance