[MattRogish]

Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s.

"If we just use RDF triples to encode everything then machines can learn that apples are fruits and fruits are good for you, thus apples are good for you! Huzzah!"

Then, Microsoft invented SOAP.

"If we just have a WSDL that explains all of our API, then we can have automated methods to communicate between services! Programmers can just auto-generate code and life is great!"

Except it doesn't work that way. Most WSDL parsers auto-generate code that you then hand-edit and maintain over time. And, you, as the programmer have to know what methods to call. SOAP is just excessive ceremony transmitted over XML - another excessively rigid structure.

So then we got JSON REST APIs. Simple text structures. Reasonable defaults. Basic vernacular. Easily understood.

What concerns me about Hypermedia APIs is that folks are using the same sorts of grandiose, architecture astronaut-y stuff that we got out of the last two failed revolutions.

Hypermedia API proponents say that REST APIs are "highly coupled" (to the data model and versioning) and don't expose workflows.

Heck, that's why REST is so pervasive - they're super easy to write and consume/interact with. Enterprisey folks are so focused on long-term extensibility and maintainability that they overlook the cognitive overhead and inability to work with it on a daily basis. And that you in fact, tend to move slower in development because you can't comprehend or follow what is going on. And that all abstractions leak, leading to libraries and tools (SavonRB) that don't quite work if an API doesn't follow the spec exactly (and they never, EVER follow the spec 100%).

My attitude is the opposite: Don't design your APIs as if you expect them to be the next 1,000 year reich. If your API stays small and nimble enough, your consumers will also be able to be flexible to accomodate it. Yes, if you have a User REST API and you decide that your app no longer has users, well, then you have to get rid of it. But adding another layer or two of hierarchy and ceremony on top via Hypermedia wouldn't solve that either! Fundamental universe changes ought to break shit!

From what I've seen (I have a subscription to designinghypermediaapis.com which is very well written) Hypermedia APIs are an over-complicated solution to a problem that has a reasonable solution. Yes, links are nice. Want to propose a "Standard" to handle links? Okay, although that's REST! If you have an Object and you want to DELETE it, I don't need to know the URL. I have a convention via REST that allows me to derive it from my data. If that's different, OK, use this thing. But Hypermedia APIs are a lot more than just links (state machines, workflows, media types, etc.)

[bct]

> Hypermedia hype has always struck me as parallel to the "semantic web" nonsense from the late 90s.

That's funny, because DHH's proud ignorance about hypermedia strikes me as parallel to the usual proud ignorance about the semantic web.

Your first 2 paragraphs don't actually say anything, they just signal your allegiances.

[iand]

You seem to be using the word REST as though you have never read any of the foundational material behind it. If you had then you'd have found that hypermedia links are an essential part of the REST philosophy and that formats like HAL are simply expressing REST concepts in JSON.

[MattRogish]

Good point; when I say "REST", I really mean: "DHH's version of REST as implemented in Ruby on Rails"

[masklinn]

AKA "not REST in any way, shape or form" AKA "good old RPC over HTTP".

[steveklabnik]

I'm one of the biggest proponents of hypermedia (been speaking about it for the last 18~ months at conferences) and I think the semantic web is bullshit.

[MattRogish]

Hi Steve,

Thanks for the reply. I'm basing my interpretation off of your http://designinghypermediaapis.com site and the associated listserv, so either I'm misinterpreting it, or we have a difference of opinion as to the complexity and utility of the proposed solution(s).

My fear is we're redefining WSDL in JSON's clothing. Yes, adding hrefs to the API isn't complex -- but the code to actually do something with it is, and that's where my spidey sense starts tingling (having just spent a few weeks in Savon/SOAP/WSDL/WSSE hell).

[steveklabnik]

> My fear is we're redefining WSDL in JSON's clothing.

Absolutely not. There is a 'WSDL in REST' called WADL, and it's _terrible_. WSDL/WADL is like static typing: you have to declare everything up front, it's super rigid, and prone to breaking. Hypermedia is like dynamic typing: it all happens late bound, it's flexible, and open to change.

> the code to actually do something with it is, and that's where my spidey sense starts tingling

Here's one of the simplest examples I can show you: the 'hypermedia proxy pattern':

https://gist.github.com/3172911

Here's the core of the code: https://gist.github.com/3172911#file-client-rb-L27-L37

This says "parse the links out and save them. When I try to load a name, if it doesn't exist, go fetch it from the link pointed to by 'self.'

This allows you to change the client behavior by modifying the server: by compressing or expanding responses, the client makes more or less requests without changing its code. Jon Moore demonstrates this with Java, Python, and XHTML here: https://vimeo.com/20781278 I demo'd this exact example at the end of my talk here: http://oredev.org/2012/sessions/designing-hypermedia-apis

Did you see my Shoes Microblogging example for ALPS? https://gist.github.com/2187514

The meat of it is here: https://gist.github.com/2187514#file-microblog_client-rb-L33... This isn't the best factored example, but I wanted to show a tiny client: this is a GUI program that can read from any ALPS compliant server (like http://rstat.us/) and read/post new status updates.

------------------------------------------------------------

What I will say is this: I don't feel it's _harder_, but I do feel it's _different_. Just like if you try to write Java in Ruby, if you try to write hypermedia APIs like another style, it will feel hard and foreign. I think it's easier to implement a number of clients over time for a hypermedia service, than it is to write a bunch of clients over time for a "Rails REST" one.

[MattRogish]

Thanks, I will dig into those examples!

[steveklabnik]

Awesome. Please let me know, and post to the list if you have questions.

By the way, my student loan creditors thank you. :)

(I'm planning on a major new iteration of the book project in the new year that's much more linear, clear, and practice driven rather than theory.)

[gamache]

What concerns me about Hypermedia APIs is that folks are using the same sorts of grandiose, architecture astronaut-y stuff that we got out of the last two failed revolutions.

You owe it to yourself to read the HAL+JSON specification: http://stateless.co/hal_specification.html

Anyone who considers a three-page spec like that astronautics probably has a low capacity for complex thought.

[nkohari]

A hint: when trying to convince, it's not a great idea to passive-aggressively insult the other party. Since they're human too, they will probably just get pissed off and write you off as an asshole. Like what I'm doing right now.

[gamache]

Given the level of respect I have for the OP's exhaustively researched points, I should not have said a thing. Someone on the Internet is wrong. My mistake.

[bdcravens]

has a low capacity for complex thought

So rude. I'm sure you have a lot of good things to say (given your other posts), but resorting to insults and ad hominems is the sort of thing that comes from those who have a low capacity for intellectual discussion.

Besides, per the URL you provided, it's a 10 page printout, not 3.

[ollysb]

Requiring a low capacity for complex thought sounds like a good API...

[irickt]

You may be surprised that the semantic web continued to develop after you dismissed it, the latest milestone being Google's Knowledge Graph.

http://news.ycombinator.com/item?id=3983179