5 ms·

Why does it matter? Ok, I agree that you probably shouldn't label something with an incorrect term, but does not having more than one URL, and not using the dif

Why does it matter? Ok, I agree that you probably shouldn't label something with an incorrect term, but does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? I personally find that sometimes I have trouble spotting the "oh! I forgot to make it DELETE instead of GET" bugs. When the parameters of the API are all in the url and/or query, it feels better encapsulated. (promise I'm not flaming, and I fully expect to get told, yes it matters, and here's why! ;)

tptacek 16y ago
Yes. In this case, it makes an enormous difference. Your application can't just go to rdio/api/1/artist/whatever to look up the tracks for an artist; it has to make a SOAP-style request for the tracks for a given artist. This isn't a style nit.
- vegashacker 16y ago
  In trying to prove you wrong and show you how easy it would be to make a similar call with the rdio API, I found out how not easy it would be to make a similar call with the rdio API. :)
- masklinn 16y ago
  It can probably be argued to be: you can't just go to rdio/api/1/artist/whatever, but you can get the exact same thing via RPC calls. I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. Furthermore, just because an API is restful doesn't mean it's well-designed, and doesn't mean it has descriptive APIs (the artist's track could just as well be in rdio/api/64D89CAC?q=42, that wouldn't inherently make the API non-restful)
  - deno 16y ago
    > I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. It should be trivial with AtomPub/GData/OData APIs. REST itself is not specific enough for that.
- mseebach 16y ago
  No, it's not REST, and it's stupid to call it that, but if you think that posting a few arguments makes something "SOAP-style", I find it hard to believe you've interacted with a SOAP web service recently.. Note: Requiring that the call are OAuth'ed, doesn't affect its RESTness.
masklinn 16y ago
> but does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? If you're expecting a REST API yes. It also significantly impairs the discovery and the cacheability of the API calls.
deno 16y ago
HTTP makes some simple guarantees in its spec regarding to the methods used. For example, GET must never have side effects. POST, PUT, DELETE always have side effects. This simple guarantees enable software like HTTP proxies to work properly. Thus by just abiding to that simple rules your API should become cachable. What REST brings to table is exchanging representations. For one thing, it makes your API actually simpler, since you don't even need a list of 'methods' like rdio has, all you need to know is the representations and methods stay the same—which should come natural if you know HTTP. The other nice thing that you get for free is that it accommodates for unreliable connectivity. In case of failure you can just retry. OTOH RPC abstracts such things away. For example if you have a call like "addSomethingToList" and you retry that method, you risk having duplicates.
- masklinn 16y ago
  > HTTP makes some simple guarantees in its spec regarding to the methods used. For example, GET must never have side effects. POST, PUT, DELETE always have side effects. Except those are of course guidelines, the API implementor is free to entirely disregard them (much to the danger of everybody) > For one thing, it makes your API actually simpler, since you don't actually need a list of 'methods' like rdio has, all you need to know is the representations and methods stay the same—which should be natural if you know HTTP. Instead of a list of methods, you get a list of methods (which do not have to stay the same, by the way) and a tree of resources. Theoretically you should be able to crawl a REST API using only the document types and the root URL, I don't think I've ever seen a "public" API letting me that. > OTOH RPC abstract such things away. For example if you have call like "addSomethingToList" and you retry that method you risk having duplicates. Yes, because if you POST the same thing twice you don't risk fucking things up... Oh you should be using PUT, not POST, you say? Good luck getting that one in browsers.
  - tesseract 16y ago
    > Except those are of course guidelines, the API implementor is free to entirely disregard them (much to the danger of everybody) Witness the Google Web Accelerator debacle.
  - 16y ago
wicknicks 16y ago
Here are some tips on how to use REST: http://www.prescod.net/rest/mistakes/ http://www.prescod.net/rest/mistakes/ http://architects.dzone.com/news/common-rest-design-pattern http://architects.dzone.com/news/common-rest-design-pattern
jrockway 16y ago
does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? Yes. You can use libraries when the service you're trying to interact with works according to some standard. An example: I have an app I wrote at work that is a JavaScript frontend powered by a REST API backend. The REST API tries to be a good REST citizen: proper HTTP implementation (201 + Location when something is created, 202 for "I will get to that eventually", etc.), consistent URL conventions, and a consistent data format. The end result is an API that is easy for humans to understand, but also easy for computers to understand: the simple CRUD code was about 10 lines of backbone.js, because my API doesn't break any conventions. This means that the code to interact with it already exists, and all I had to do was make the web page look pretty. This is a good use of programmer resources, now and in the future. In the present, I didn't have to do any work to make a pretty GUI. In the future, someone that wants to pull data from my API will not have to swear at me -- everything you can do is easily discoverable by starting from the root resource.
- Hixie 16y ago
  You can have a well-defined spec that's easy to understand without having to shoe-horn your API into HTTP's document-orientated semantics.
  - stanleydrew 16y ago
    Sure, just don't call it REST.

tptacek 16y ago

Yes. In this case, it makes an enormous difference. Your application can't just go to rdio/api/1/artist/whatever to look up the tracks for an artist; it has to make a SOAP-style request for the tracks for a given artist. This isn't a style nit.

vegashacker 16y ago
In trying to prove you wrong and show you how easy it would be to make a similar call with the rdio API, I found out how not easy it would be to make a similar call with the rdio API. :)
masklinn 16y ago
It can probably be argued to be: you can't just go to rdio/api/1/artist/whatever, but you can get the exact same thing via RPC calls. I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. Furthermore, just because an API is restful doesn't mean it's well-designed, and doesn't mean it has descriptive APIs (the artist's track could just as well be in rdio/api/64D89CAC?q=42, that wouldn't inherently make the API non-restful)
- deno 16y ago
  > I often think that, via REST APIs and content negotiations, API can become browseable and self-descriptive but I've yet to see any example of such a thing. It should be trivial with AtomPub/GData/OData APIs. REST itself is not specific enough for that.
mseebach 16y ago
No, it's not REST, and it's stupid to call it that, but if you think that posting a few arguments makes something "SOAP-style", I find it hard to believe you've interacted with a SOAP web service recently.. Note: Requiring that the call are OAuth'ed, doesn't affect its RESTness.

masklinn 16y ago

> but does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? If you're expecting a REST API yes. It also significantly impairs the discovery and the cacheability of the API calls.

deno 16y ago

HTTP makes some simple guarantees in its spec regarding to the methods used. For example, GET must never have side effects. POST, PUT, DELETE always have side effects. This simple guarantees enable software like HTTP proxies to work properly. Thus by just abiding to that simple rules your API should become cachable. What REST brings to table is exchanging representations. For one thing, it makes your API actually simpler, since you don't even need a list of 'methods' like rdio has, all you need to know is the representations and methods stay the same—which should come natural if you know HTTP. The other nice thing that you get for free is that it accommodates for unreliable connectivity. In case of failure you can just retry. OTOH RPC abstracts such things away. For example if you have a call like "addSomethingToList" and you retry that method, you risk having duplicates.

masklinn 16y ago
> HTTP makes some simple guarantees in its spec regarding to the methods used. For example, GET must never have side effects. POST, PUT, DELETE always have side effects. Except those are of course guidelines, the API implementor is free to entirely disregard them (much to the danger of everybody) > For one thing, it makes your API actually simpler, since you don't actually need a list of 'methods' like rdio has, all you need to know is the representations and methods stay the same—which should be natural if you know HTTP. Instead of a list of methods, you get a list of methods (which do not have to stay the same, by the way) and a tree of resources. Theoretically you should be able to crawl a REST API using only the document types and the root URL, I don't think I've ever seen a "public" API letting me that. > OTOH RPC abstract such things away. For example if you have call like "addSomethingToList" and you retry that method you risk having duplicates. Yes, because if you POST the same thing twice you don't risk fucking things up... Oh you should be using PUT, not POST, you say? Good luck getting that one in browsers.
- tesseract 16y ago
  > Except those are of course guidelines, the API implementor is free to entirely disregard them (much to the danger of everybody) Witness the Google Web Accelerator debacle.
- 16y ago

wicknicks 16y ago

Here are some tips on how to use REST: http://www.prescod.net/rest/mistakes/ http://www.prescod.net/rest/mistakes/ http://architects.dzone.com/news/common-rest-design-pattern http://architects.dzone.com/news/common-rest-design-pattern

jrockway 16y ago

does not having more than one URL, and not using the different HTTP methods really make a difference in terms of programmer usability? Yes. You can use libraries when the service you're trying to interact with works according to some standard. An example: I have an app I wrote at work that is a JavaScript frontend powered by a REST API backend. The REST API tries to be a good REST citizen: proper HTTP implementation (201 + Location when something is created, 202 for "I will get to that eventually", etc.), consistent URL conventions, and a consistent data format. The end result is an API that is easy for humans to understand, but also easy for computers to understand: the simple CRUD code was about 10 lines of backbone.js, because my API doesn't break any conventions. This means that the code to interact with it already exists, and all I had to do was make the web page look pretty. This is a good use of programmer resources, now and in the future. In the present, I didn't have to do any work to make a pretty GUI. In the future, someone that wants to pull data from my API will not have to swear at me -- everything you can do is easily discoverable by starting from the root resource.

Hixie 16y ago
You can have a well-defined spec that's easy to understand without having to shoe-horn your API into HTTP's document-orientated semantics.
- stanleydrew 16y ago
  Sure, just don't call it REST.