I've been reading about this new-fangled thing called Hypermedia API's. Apparently, this comes as a result of REST failing and now we need something even newer. A hypermedia API isn't really anything new, just as REST wasn't anything new. The problem stems more from the fact that few people actually understand what they have on their hands and how to use it.
My cursory understanding of a Hypermedia API is that it does for web based API's what HTML did for Documents on the web. IE, in theory it makes an API self descriptive and navigable, the way an HTML website is - you can point a generic content consumer (browser in the case of HTML) at it, and its viewable and usable by a human. Simple things like using URI's instead of some internal ID number to refer to other resources (like a simple link in HTML) or some kind of known data structure to define the inputs to a resource (HTML FORM).
That's all well and good, and in many ways useful to do. But API's aren't consumed by a human, but rather another machine. So the analogy of saying Hypermedia API's are like HTML is kinda wrong. And its not going to work just like that. I like what David of Ruby On Rails fame has to say about it.
I think the real problem here is the same reason why REST (and various frameworks) often fails, and that's because of a misunderstanding that goes back many years; that of the Model. That's the M in MVC and I think too many people get it wrong. These days, Model usually means "Database record". So, its natural when you take a typical modern framework that makes Model synonymous with Database and make a "REST" API where its doing not much more than just exposing those models and a CRUD interface. But thats not REST - REpresenational State Transfer. Thats just tunneling your database to the browser.
See, models, in the original MVC, were meant to be just that.. models. Not the real thing as internally manipulated by arcane code written by programmers who think that way. Models, as in, a conceptual way of viewing something. Typically, a way of viewing something that makes sense to the typical person who might be using the system.
That's what make HTML so great. Anybody could come along to a website, and view it. Anybody could quickly learn to click on hyperlinks to find more stuff to view. Its not so much that the HTML describes itself and how to interact with it (even though it does to a degree). Its that the HTML was (if it was done right) designed to be used by a human.
API's are typically not designed for a human, right? So our brains fall out of our heads and we just offer up direct versions of database objects. But that's not right. What happened to the REpresentational part? Just because it's API doesn't mean it can't make sense to an end user. Isn't that kind of the point of API anyway? To provide an abstraction to your data?
REST implementations fail often because they are not providing representations of the internal data, nor do they provide much real state other than the HTTP verbs. So Hypermedia API was "invented". But people are still serving up literal translations of database tables instead of coming up with sensible, intermediate Models that make sense to the consumer of the API.
This is also aside from the fact that people also get the V in MVC wrong. Views were never meant to be these statically defined immutable bricks that fit perfectly to the model. They were supposed to be ephemeral things that were created on the fly as needed to present the model to the user under the guidance of the controller. Most MVC frameworks get it all wrong.
So in summary, you're doing it all wrong! Lets stop arguing about REST and Hypermedia API's and thinking these tools will fix our problems, when really the problem is more about the data we are trying to let a user manipulate. If we get that data right, that Model, the rest will come.
