4 ms·

I designed a REST API with a "well-documented" HATEOAS representation (collection+json). The primary requirement was to ensure there was no caller-side languag

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.

recursivedoubts 6y ago
> 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.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...
- ClumsyPilot 6y ago
  So far I have not experienced HATEOAS deliver value over a wiki with good documentation - that seems like better effort.
  - dragonwriter 6y ago
    > 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.
    - acidbaseextract 6y ago
      > 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.

recursivedoubts 6y ago

> 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.html https://intercoolerjs.org/2016/05/08/hatoeas-is-for-humans.h...

ClumsyPilot 6y ago
So far I have not experienced HATEOAS deliver value over a wiki with good documentation - that seems like better effort.
- dragonwriter 6y ago
  > 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.
  - acidbaseextract 6y ago
    > 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.