Comment by clusterhacks | Hacker News Reader

Comment by clusterhacks | Hacker News Reader

Parent Full thread

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.

Reply on news.ycombinator.com