I really like the idea of HATEOAS but I have never seen hypermedia controls done in the wild across any companies I've worked for nor on any client projects. I think it's very cool but a lot of development patterns don't consider it.
> It's impossible for me to see how it would be possible to write a HATEOAS client, and I can't in practice see anyone doing so.
There's nothing complicated about a client that understands Hypermedia links. You start at the root, it'll give you a set of links to follow, and you recurse. Here's a browser that can take a HATEOAS-compatible API and will let you work your way through the API: http://dracoblue.github.io/hateoas-browser/
> Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort.
Correct. HATEOAS is a neat parlor trick: point a dumb client at your API and watch it enumerate all the possible operations. Wow! The problem is that APIs aren't consumed that way, they're consumed by humans who need to decide which API calls to make based on user actions in the application... so developers will resort to consulting documentation in order to piece together the correct calls in the correct order. That's not something you can encode through Hypermedia. At best you can just model the relations between calls, but not the "how" or "why" of everything.
I meant a user friendly client, not something aimed at API developers. Sure you can create something which is aimed at Developers, but it's not presenting the data in a way any user would understand, or in a way that a UX expert can flex.
Fundamentally, your display logic should not be linked to your API schema, but HATEOAS essentially enforces that, because you can't predict what links will be available.
> I meant a user friendly client, not something aimed at API developers. Sure you can create something which is aimed at Developers
Just for clarity, are you talking about API Developers or API Client Developers? I would see the primary beneficiaries of HATEOAS being developers consuming your API - i.e. client developers.
The HAL hypermedia format is in use at Comcast, powering the Xfinity TV API. Not only does it take advantage of hypermedia and HATEOAS, it also splits requests/responses in order to make the most use of HTTP caches. https://boston2016.apistrat.com/speakers/ben-greenberg
Dunno if you're serious about not seeing how one could write a HATEOAS-driven client library or if I'm being trolled, but here's one that I wrote a couple of years ago: https://github.com/gamache/hyperresource There are many others as well (especially for the HAL format).
I'm definitely not trolling - it's just that's not how clients work.
I don't write a client by doing a random walk through the API until I get to the information I need, I want to call the API that I know I need to give me the information that I want, and for performance, I want it all to be returned on a single call ideally.
e.g. If I want user B's playlist, I don't want to have to crawl:
At this point aren't you still hard coding commands, but using "links" rather than URLs? And doesn't the dependency on every link in the chain outweigh one - easily maintained - URL?
You're hard-coding 'terms' from a hypermedia 'vocab'.
The thing is, if you use well-known terms, your client will work against ANY API that uses those terms, not just the one that you coded it to work against.
Not only that, but the APIs will have flexibility to move things around, or delegate functionality to other hosts by linking through.
As for the cost of walking the chain, once a target resource has been found the can be cached, and you only need to rewalk if the resource 404/410s.
Except the browser really isn't. It has strict behavior, and the list of what happens as it loads that hypermedia is deterministic and known to both the client and server. The difference between what happens when the browser sees a "stylesheet" link reference and a "icon" one is significant, and not something the browser is expected to figure out on its own.
The HATEOAS idea is that you throw that out, just use some aribitrary XML (sorry, "hypermedia") to return your application state, and that this somehow magically empowers the client to be able to puzzle out all the things that can be done to your state.
Except it can't. It's just arbitrary junk if you don't have a schema and a spec. And it will always be so. Discoverability is (1) not something you can get from a data structure and (2) something best provided by documentation, not runtime behavior.
You obviously need SOME spec or schema to be able to understand what to do with hypermedia, but it really comes down to how many things you have to define. It lets you define a smaller number of pieces and their functionality, and then lets you compose those smaller pieces into larger functions, and even create new combinations after a client is created without having to update the client.
I think you have a completely wrong idea about HATEOAS. The application is certainly expected to be able to handle the data format, not figure out by magic. As Fielding writes in his dissertation, REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types. The client is certainly supposed to understand these data types, that's why they must be standard (like HTML). The dynamic part comes from the formats themselves, which may have variable or optional elements depending on the state of the resource.
Someone needs to fix the wikipedia page on HATEOAS then, because it says exactly the opposite of what you just did in its third sentence.
(One of the other problems with Fielding's work is precisely this word-salad of new jargon and usages, leading to exactly this kind of what-does-it-REALLY-mean-anyway confusion. But that's an argument for a different thread.)
From the wikipedia page: "The media types used for these representations, and the link relations they may contain, are standardized."
As for Fielding's work having a word-salad of new jargon and uses, I frankly didn't get that by reading his dissertation, which I found quite clear. There are a few concepts (Resources, Representations), but I think they make sense in the context.
> Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort.
It depends, it's just a way to reduce coupling between a webservice and its client apps. Instead of hardcoding all the URL endpoints into the client, the client has to follow the links provided by the webservice instead. If this layer of indirection has advantages for you depends on your use case. You could compare it to using DNS instead of static IPs. Static IPs work fine but you end up with more coupling than using DNS.
If I remove the reference to a link in the response, it doesn't remove the clients need to:
a) know how to retrieve that link (i.e. what resource do I need to retrieve in order to get that response)
b) requirement for that link to exist (they still need that link).
Requiring that a client know that to get data Bar, they need to retrieve resource A, follow the link at foo[n]._link to retrieve resource B, and then following the link at _link.bar feels like a total non starter, and actually increases coupling.
>But yes the client still has to know what to do in advance.
According to Roy Fielding[1] (who came up with the concepts of ReST and HATEOAS:
"A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience"
So if an application doesn't rely on "standardized media types", and "the client still has to know what to do in advance", then it seems like whatever you're doing, it isn't HATEOAS after all.
I don't think you and your parent mean the same thing. The client "has to know what to do in advance" in the sense that the human building the application needs to know what user interface they want to build, and know how the API works (in advance) in order to use it to populate the interface.
If you have an extremely dumb interface that just displays fields in API responses, then ok... but that's a very trivial UI that accounts for... basically no useful products ever.
I'll be honest, I stopped reading the article as soon as it mentioned Hypermedia, because I instantly saw the problem as the author being upset that Swagger is not Hypermedia.
I have a really hard time seeing APIs ever reaching that level of standardization, and I'm tired of having the Hypermedia discussion. I generally support logically organized APIs with good documentation. As long as those things are true, I'm happy for the API.
HATEOAS if your API needs to maintain state AND you want links AND you want a standard. A game API would be a good use case.
REST if your API should not maintain state between requests. If you want links as a part of your response (and want to use a standard) use e.g. HAL or JSON API.
