There's two massively under-addressed problems with the HATEOAS constraint: 1. Code-on-demand requires coupling of technology stack of client and server. (If y

There's two massively under-addressed problems with the HATEOAS constraint: 1. Code-on-demand requires coupling of technology stack of client and server. (If you're going to assume your clients can run javascript or x-technology, where is the decoupling?) 2. Out-of-band communcation. Some of the recommendations I've heard have been along the lines of: let's avoid out-of-band communication in API docs etc and have it completely discoverable based on the media type. "And what happens if the media-type isn't sufficient to represent your use case?" "That's easy, you create your own media type" So in order to have no need for API docs for an actual API, I create a completely separate media type (which will need its own RFC type specification, or at the very least its own API docs). This is purely academic, and I still think that nobody is doing it because only those that have tried it or seriously thought through the implications are naysayers. Nobody who's actually built a system like this is coming forth and explaining the benefits. Maybe if we get some media type that everyone starts using because (unlike XML/JSON etc) it supports full REST-like semantics i.e. forms for POSTing and not just hyperlinks for GET requests, then we may see the purported benefits. But you still run into the problem of expressing field level validation messages in a 422 response. And expressing the valid values in a reasonable way in a template for an object. Yes, expressing a String or a DateTime object or any other relatively primitive data type with simple validations: presence of, within array of, valid email, valid phone number may be possible. But most of the time you can't predetermine this kind of contract up front. So there's no way of me, the producer of the API, expressing to you, the consumer of the API, that this particular regex completely satisfies my business requirements in all circumstances. If I could nail down the expression of the required values for an API call in any sufficiently complex business system and convey it to you in some easy to digest, computer-understandable format then I'm sure we'd be gold. But reality sets in and you realise you've added a whole bunch of cruft to every API call, and a whole bunch of unnecessary API calls to express some theoretical idea by an academic who admits that he's too busy to actually go away and start building some of these systems. Not only that, you're making it harder for your consumers to integrate. (Unless they are using an already known media-type, which is a chicken and egg situation as the closest we have to being good enough is HTML, and you try explaining to API consumers, yes the future is HTML, and yes I want you to parse HTML to get the data from my API). We could start saying, well hell to efficiency as technology consistently improves, but we're dealing with routing packets over the internet at approximately the speed of light. There is a real-world upper limit to this stuff and we need to improve efficiency because if you add 10 extra HTTP requests per API call, your users _will_ notice. This stuff matters. Hell, even if these are not user critical applications and there is some as yet not understood benefit to the world as a whole having asynchronous processes running in the backends of our systems optimising some problem space and searching for solutions on their own, then we still have another real world problem. There has to be some short to medium to even long-term benefit to building this kind of system to someone. Nobody wants to build this theoretical hypermedia, semantic web on their own dollar when there is no visible pay-off in the near future or even idealistic theoretical pay-off in the long term.