4 ms·

As others have alluded to, it's all fine & dandy to try to adhere to the guidelines of "pure REST" but in reality, you have customers/users who know enough to c

As others have alluded to, it's all fine & dandy to try to adhere to the guidelines of "pure REST" but in reality, you have customers/users who know enough to construct a web request, but don't really understand what HTTP verbs are, what HTTP headers are etc. In my experience, your average developer (of course, not anyone who'd frequent HN!) really doesn't have a good grasp of how HTTP works. So the way you combat this problem is either 1) You provide client libraries in the popular languages so your users can download those and not have to make requests directly. This way you can put versioning and accepted response types in the headers instead of the URL OR 2) You put everything in the URL and you're done with. In my company, we initially went with 1) but then realized that just putting a version & format (.json, .xml etc.) in the URL lead to much fewer "Your API isn't working" emails.

deleted 13y ago
[deleted]
- johns 13y ago
  I think you misinterpreted the parent post. You two are almost certainly talking about the same kind of REST aka the mainstream understanding of it popularized by APIs like Twitter, Twilio, Stripe, etc. The "real/pure REST" folks are talking about by-the-dissertion Fielding's REST which is far more complicated and confusing and is probably not a good idea for a public API. It goes beyond verbs and pretty URLs. Look into Hypermedia APIs. That's the One True REST.
  - MichaelGG 13y ago
    Yeah, Twilio's API isn't REST as it has versions and content types in the URIs. Plus, you're supposed to construct URIs (and all the clients do this AFAIK, since it'd be idiotic waste of a roundtrip not to). E.g. "/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}" Yet it's the closest thing I've seen held up as a "good RESTful API". In practise, it just means I've got to write more code to shove parameters into the URI and body. "REST" as used by pretty much everyone is just a codeword for "we didn't use SOAP!". And maybe the URLs are more than just "/FooService" and maybe they use HTTP verbs.
MichaelGG 13y ago
Sometimes I feel like I'm missing something, but then I read specs and I read REST manifestos and I just don't see the value over RPC style. When coding against an API, clients are pretty much always want to make "function calls" and get values back. So even if the URL is just "api.localhost.com/apiv1.handler" and everything goes into a XML or JSON body, what's the drawback? REST advocates insist that URLs shouldn't be constructed either. So every site that boasts "REST" but then goes on to say accounts are at "/account/{id}" aren't really RESTful. (You're supposed to find the account URI via a search or save it from creation.) Spreading the values of the "function call" all over the place just makes your plumbing code more complicated, but the end result to the user will still be "GetAccount(id) -> Account". Plus, the concept of making the URIs all be nouns then cramming your logic into the few HTTP verbs is just odd. OK, so HTTP has a DELETE method. Why is that somehow intrinsically better than <action name="DELETE" id="123" />? So far I've yet to see a real REST API where I say "oh wow, that's a lot easier to handle". Maybe I'm looking at it wrong, and ease-of-use for programmers isn't a goal.
- icebraining 13y ago
  I agree with you. For most people, switching to REST is useless, because they're still attached to the conceptual framework of RPC. We're still in the dark ages, re-writing the wheel again and again and again, coding clients for each single service out there. It's not wonder that REST seems useless. But there's a vast network of services, far bigger than all the RPC APIs out there, that isn't like that. Where clients can connect to different services - even services made years after them, with functionality they couldn't have anticipated - without having to be tailored to them. Where the user can switch the provider of a specific service without having to switch clients, because the protocols are standard and compatible. I'm talking, of course, about the HTML Web. Where people implement RESTful services without even knowing what they are, just because following a standard is just painfully obvious. REST is the way we can implement something better; instead of dumb clients, we can have smart agents that interact with the rest of the web as browsers now do, but without the user hand-holding it. And gradually switching RPC to REST is the only way to accomplish that.
  - 13y ago

deleted 13y ago

[deleted]

johns 13y ago
I think you misinterpreted the parent post. You two are almost certainly talking about the same kind of REST aka the mainstream understanding of it popularized by APIs like Twitter, Twilio, Stripe, etc. The "real/pure REST" folks are talking about by-the-dissertion Fielding's REST which is far more complicated and confusing and is probably not a good idea for a public API. It goes beyond verbs and pretty URLs. Look into Hypermedia APIs. That's the One True REST.
- MichaelGG 13y ago
  Yeah, Twilio's API isn't REST as it has versions and content types in the URIs. Plus, you're supposed to construct URIs (and all the clients do this AFAIK, since it'd be idiotic waste of a roundtrip not to). E.g. "/2010-04-01/Accounts/{AccountSid}/IncomingPhoneNumbers/{IncomingPhoneNumberSid}" Yet it's the closest thing I've seen held up as a "good RESTful API". In practise, it just means I've got to write more code to shove parameters into the URI and body. "REST" as used by pretty much everyone is just a codeword for "we didn't use SOAP!". And maybe the URLs are more than just "/FooService" and maybe they use HTTP verbs.

MichaelGG 13y ago

Sometimes I feel like I'm missing something, but then I read specs and I read REST manifestos and I just don't see the value over RPC style. When coding against an API, clients are pretty much always want to make "function calls" and get values back. So even if the URL is just "api.localhost.com/apiv1.handler" and everything goes into a XML or JSON body, what's the drawback? REST advocates insist that URLs shouldn't be constructed either. So every site that boasts "REST" but then goes on to say accounts are at "/account/{id}" aren't really RESTful. (You're supposed to find the account URI via a search or save it from creation.) Spreading the values of the "function call" all over the place just makes your plumbing code more complicated, but the end result to the user will still be "GetAccount(id) -> Account". Plus, the concept of making the URIs all be nouns then cramming your logic into the few HTTP verbs is just odd. OK, so HTTP has a DELETE method. Why is that somehow intrinsically better than <action name="DELETE" id="123" />? So far I've yet to see a real REST API where I say "oh wow, that's a lot easier to handle". Maybe I'm looking at it wrong, and ease-of-use for programmers isn't a goal.

icebraining 13y ago
I agree with you. For most people, switching to REST is useless, because they're still attached to the conceptual framework of RPC. We're still in the dark ages, re-writing the wheel again and again and again, coding clients for each single service out there. It's not wonder that REST seems useless. But there's a vast network of services, far bigger than all the RPC APIs out there, that isn't like that. Where clients can connect to different services - even services made years after them, with functionality they couldn't have anticipated - without having to be tailored to them. Where the user can switch the provider of a specific service without having to switch clients, because the protocols are standard and compatible. I'm talking, of course, about the HTML Web. Where people implement RESTful services without even knowing what they are, just because following a standard is just painfully obvious. REST is the way we can implement something better; instead of dumb clients, we can have smart agents that interact with the rest of the web as browsers now do, but without the user hand-holding it. And gradually switching RPC to REST is the only way to accomplish that.
- 13y ago