5 ms·

The HATEOAS wonks are crazy, IMO. Most people who consume your API will have no idea what HATEOAS is and they sure as hell won't care. What will they care about

by notJim 14y ago

The HATEOAS wonks are crazy, IMO. Most people who consume your API will have no idea what HATEOAS is and they sure as hell won't care. What will they care about? The URL to hit to get the data they want. They will hardcode that URL in their app, too, so expect any changes to it to require a great deal of fanfare to re-educate your users. 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.

steveklabnik 14y ago
> Most people who consume your API will have no idea what HATEOAS is and they sure as hell won't care. What will they care about? The URL to hit to get the data they want. 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 http://news.ycombinator.com/item?id=4949311 GitHub, BalancedPayments(YC W11), and others are finding real benefits today.
- notJim 14y ago
  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.

by notJim 14y ago

steveklabnik 14y ago

> Most people who consume your API will have no idea what HATEOAS is and they sure as hell won't care. What will they care about? The URL to hit to get the data they want. 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 http://news.ycombinator.com/item?id=4949311 GitHub, BalancedPayments(YC W11), and others are finding real benefits today.

notJim 14y ago
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.