The Future is Hypermedia APIs

You might be right, as you've clearly thought about this more than I have. I have a couple of thoughts though.

> A few years ago, before Rails made "REST" popular, this exact same statement was made. "Nobody is going to want to learn about PUT and DELETE. They just want to do everything over POST."

> This is an education problem. We're still in the early days of this stuff.

The developers I was working with also had a lot of trouble with REST. I had to explain repeatedly what PUT, DELETE, GET and POST were (they weren't really familiar with HTTP at all), and that they weren't doing RPC calls. On the one hand, I feel REST is a simple and elegant concept and its not much to ask someone to understand, but on the other hand, when I build an API, I want it to be easy to use and accessible to developers of wide skillsets and levels of experience. To me, sacrificing some of my desire for elegance is worth it if it reduces the level of “education” required.

> One thing that's nice about hypermedia is that you can lead clients to wherever you want them to go. You're free to change things at any time. Have a mobile app? Make less features, and make the request paths shorter. Have a desktop app? Make them longer, add more stuff. It's up to you. Nobody says that you have to complete N steps to do anything unless your server does.

Either I'm not understanding you, or this seems totally backwards to the way APIs should work. You build an API so that users can do things with their data/your service that you haven't thought about, or cover edge cases that aren't interesting to you. I feel like my API should enable people to build the things they want, not limit and encumber them so that I can have my pretty hypermedia. In other words, I'm not interested in leading clients places. I'm interested in where they lead me.

> Either I'm not understanding you, or this seems totally backwards to the way APIs should work.

The best hypermedia API that you know of is ATOM and ATOMpub. ATOM is data exchange, but it also describes how to edit entries and delete them. This allows many services to expose ATOM, many to consume it, and everything is peachy keen.

The issue with 'just exposing data' is that you couple the business processes that your APIs do to organizations outside of your control. By exposing your processes (the 'state machine' of REST), you remove that coupling.

You may want to see this talk: http://oredev.org/2012/sessions/designing-hypermedia-apis

Of course, there are many APIs where 'just exposing data' makes sense. Hypermedia won't help you there, so don't use it. But if you want to build lasting, scalable, evolveable systems, then hypermedia is for you. If you just want to expose some data, then it's not.

A few thoughts:

* Mike Kelly (the author of the HAL spec) is not aiming for a universal API client http://news.ycombinator.com/item?id=4949357 (and also seems to be under the impression that no-one else is either).

* A universal client seems impossible because APIs will typically need to use service-specific link relations for all "interesting" relations (e.g. product, author). You might be able to share generic link relations (like those in IANA's table: http://www.iana.org/assignments/link-relations/link-relation...), but sharing only these doesn't seem to be worth the effort.

* Hypermedia-powered experimentation is kinda cool, but you're still going to need something to drive it (see e.g. Kelly's HAL browser http://haltalk.herokuapp.com/explorer/hal_browser.html#/), at which point you might as well write a full-fledged API dashboard.

I'm confused about something. The author's "simple and easy solution" to the problem of people saving API URLs is to have a "bookmark relation" link; but all that means is assigning a unique, permanent name to the resource so people can find it again. Why wouldn't you just design your API so the API URL is that unique, permanent name? The "bookmark" link "identifier" ends up being a URL anyway; why not make it the API URL to start with?

> This kind of thing sounds great for exploratory development, but undesirable (for the reasons I outlined previously) for an actual production app.

We actually do this in our production app. The only URL we actually hardcode in the app is the root URL for the account currently logged into. (And a few other urls unrelated to the account, but that's honestly just pure laziness).

User logs in - we get the account (root resource)

Bootstrap the JS - we get a subresource of the account and request it, populating the initial UI

User interacts with UI - generates a GET to a URL we got from another resource, repopulates the UI with relevant data from that resource. Rince, repeat.

Doing this has made changing our API structure over the course of development a lot easier.

> I hope you're used to waiting :).

I am :). But I look at how much faster html5 went from concept to production because it was pushed by the browsers, and I experience an $optimism++. Things are moving in the right direction, IMO.