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."
> They will hardcode that URL in their app, too,
This is an education problem. We're still in the early days of this stuff.
> One for when the URL works like it should, and another for when it changes and they have to use hypermedia to find it again.
This is a tooling problem.
> You're seriously telling me that you want to force users of your API to make N * depth of resource requests, instead of just going straight there, when each request takes 100 ms or more?
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.
> Users (and search engines) will save your URLs, so if you break them, you will lose traffic.
Right. So what do we do on the web? We 301 redirect until we don't have enough traffic to care anymore. Same thing with your API.
> The future is almost never $elegantly_designed_complex_system. It's almost always a pile of garbage, with a few humans sitting around sorting through the garbage to find the thing they want.
Luckily, Hypermedia is the _opposite_ of Big Design Up Front. It lets you evolve over time. Partial application still yields benefits.
Please see my comment over here: http://news.ycombinator.com/item?id=4949311 GitHub, BalancedPayments(YC W11), and others are finding real benefits today.
> 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.
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.
You should try using the SQL analogy instead of RPC, as this is much closer to what a "traditional" developer might expect. With REST, one is not doing a procedure call, but one is querying to create/retrieve/update/delete data. Of course, there might be some procedures behind it, but to a client it's just a data query (just like SQL has stored procedures of its own).
Maybe you should've built them a client too? https://www.braintreepayments.com/braintrust/when-rest-isnt-...
I've heard great things from people updating their API clients to use our new hypermedia stuff. So we're pushing forward with our hypermedia experiments at GitHub. People are still free to optimize for speed (reduce the number of HTTP calls in environments where it really matters) or even development speed (hardcoding a few API calls instead of dropping in a full client library) if they like.
I'm not strictly advocating HATEOS. Hypermedia and HATEOS are related but not the same concept. I am very strongly advocating hypermedia, as I believe it it greatly reduces the complexity of interacting with an API.
Never having to build a URL by hand is great! Being able to just grab a field from a resource, and go do a GET on its value is very easy to code, even if that process involves finding a link with a certain relation. You speak of complexity, and I'm speaking of convenience.
With that convenience also comes the ability to automatically crawl the data with good solid knowledge of how each resource relates to others, enabling the ability to create massive graphs of information. Like wikipedia has for humans to read, but structured and standard for computers to parse.
> His theoretical (well, implementations certainly exist) universal REST client only works when every API you want to consume standardizes to presenting the information in the same format.
That sounds like a great day to me.
This kind of thing sounds great for exploratory development, but undesirable (for the reasons I outlined previously) for an actual production app.
> That sounds like a great day to me.
I hope you're used to waiting :).
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.
For example production apps, see this comment, and the one it links to: http://news.ycombinator.com/item?id=4950877
(Ohhh, hypermedia. ;) )
In theory, the URN solution could work, but it's far more complex and requires more maintenance than simply having URLs that can be relied upon. His solution to the problem of breaking bookmarks is also a lot of work for consumers of his API--they have to two codepaths: one for when the URL works like it should, and another for when it changes and they have to use hypermedia to find it again. Again, most consumers of the API aren't going to give a shit. They are going to hardcode URLs and complain when you break them.
Not only that, but consider the implications of an API that requires you to start from the beginning each time for mobile traffic. Each request over a mobile connection takes an eternity due to high latency. You're seriously telling me that you want to force users of your API to make N * depth of resource requests, instead of just going straight there, when each request takes 100 ms or more? Okay, so maybe you can cache it, but that just means the user's first impression of the app is that it takes 500 ms just to do the first thing. Pretty shitty first impression.
The comparison to a browser doesn't hold much water for me either. Users (and search engines) will save your URLs, so if you break them, you will lose traffic. If I try to go to my bookmark and get a 404, you really think I'm going to take the time to find your page again? Maybe, but it's much more likely I'm going to shake my head and close the tab. Of course Google will eventually find your page again, but it will have lost the SEO points it gained, which means you'll have to start rebuilding your SEO from scratch.
The other issue with the browse as hypermedia engine that he leaves out is the human brain. The human brain is excellent at extracting information from text data, so there doesn't need to be any kind of common standard or format to browse a webpage. The brain just figures it out that when you say click: [here], [here] is a link that goes to whatever you were just talking about. That dramatically reduces the burden on webpage authors to conform to any kind format. His theoretical (well, implementations certainly exist) universal REST client only works when every API you want to consume standardizes to presenting the information in the same format.
I drank the HATEOAS Kool-Aid when I first learned about REST too, and then I built a beautiful API that used it. What did the developers ask for? A list of URLs.
The future is almost never $elegantly_designed_complex_system. It's almost always a pile of garbage, with a few humans sitting around sorting through the garbage to find the thing they want.