4 ms·

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 e

by 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.
- deno 16y ago
  Okay, first this was of course nit-picking, as I just hoped to get across the point, that REST is not just pretty URLs. > Except those are of course guidelines Well, obviously. > 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. Well, yes. But those are already established and if you're exchanging representations as REST demands, you shouldn't need anything more than GET, POST, PUT, DELETE and PATCH to manipulate data. > 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. Sun tried to do that for their cloud computing API, I think they're the ones that created the term RESTful where you'd use elegant concepts like <link> in your representations to advertise available actions. > Yes, because if you POST the same thing twice you don't risk fucking things up... If you do it properly with versioning/unique ids where appropriate, then all your calls should be re-triable or at least fail. > Oh you should be using PUT, not POST, you say? Good luck getting that one in browsers. You can create browser API (with proper CSRF protection etc. btw) that acts as a [server-side] client to your REST API. Also I see most usage of any REST APIs from browsers coming from Javascript based clients, which usually don't impose such limitations.
  - masklinn 16y ago
    > that REST is not just pretty URLs. REST and pretty URLs are very much orthogonal indeed.
- rapala 16y ago
  >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. Oh yes you have. Ever browsed a ftp server with your browser? That is a REST API, using HTTP and FTP for transportation and HTML and WHATEVER for the actual data. You can start from the root of the server (or more commonly, from /pub/) and crawl through the file hierarchy as much as you like. But your point is valid. Not many APIs allow to "crawl" the data, even though one of the four guiding principles for interface is: Hypermedia as the engine of application state "If it is likely that the client will want to access related resources, these should be identified in the representation returned, for example by providing their URIs in sufficient context, such as hypertext links." REST is an architecture style, not a protocol. HTTP is protocol well suited for use in a RESTful system. The API in question violates REST (atleast) by not using the methods provided by HTTP.
bobbyi 16y ago
GET is idempotent. It's fine if the first GET request to a resource has side effects (like creating it on demand).
rosser 16y ago
GET must never have side effects. POST, PUT, DELETE always have side effects. Pedantry: because they're supposed to be idempotent, POST, PUT, and DELETE should only have side-effects the first time they're issued against a given resource. Also, RFC 2616 uses "SHOULD NOT", as opposed to "MUST NOT" to describe the behavior of the "safe methods". To wit, "in particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval."
- cperciva 16y ago
  POST is not idempotent. POST is explicitly what you should use for non-idempotent operations. This is why your web browser issues "need to resend a form" warnings when you return to earlier pages.
  - rosser 16y ago
    Oops. Looks like, when I double-checked the RFC, my brain stuck POST in there. That'll show me for trying to be pedantic in the middle of doing thirteen other things. Thanks for the correction.
- tmhedberg 16y ago
  POST is not defined to be idempotent, although you're correct about PUT and DELETE.

by deno 16y ago

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.
deno 16y ago
Okay, first this was of course nit-picking, as I just hoped to get across the point, that REST is not just pretty URLs. > Except those are of course guidelines Well, obviously. > 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. Well, yes. But those are already established and if you're exchanging representations as REST demands, you shouldn't need anything more than GET, POST, PUT, DELETE and PATCH to manipulate data. > 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. Sun tried to do that for their cloud computing API, I think they're the ones that created the term RESTful where you'd use elegant concepts like <link> in your representations to advertise available actions. > Yes, because if you POST the same thing twice you don't risk fucking things up... If you do it properly with versioning/unique ids where appropriate, then all your calls should be re-triable or at least fail. > Oh you should be using PUT, not POST, you say? Good luck getting that one in browsers. You can create browser API (with proper CSRF protection etc. btw) that acts as a [server-side] client to your REST API. Also I see most usage of any REST APIs from browsers coming from Javascript based clients, which usually don't impose such limitations.
- masklinn 16y ago
  > that REST is not just pretty URLs. REST and pretty URLs are very much orthogonal indeed.
rapala 16y ago
>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. Oh yes you have. Ever browsed a ftp server with your browser? That is a REST API, using HTTP and FTP for transportation and HTML and WHATEVER for the actual data. You can start from the root of the server (or more commonly, from /pub/) and crawl through the file hierarchy as much as you like. But your point is valid. Not many APIs allow to "crawl" the data, even though one of the four guiding principles for interface is: Hypermedia as the engine of application state "If it is likely that the client will want to access related resources, these should be identified in the representation returned, for example by providing their URIs in sufficient context, such as hypertext links." REST is an architecture style, not a protocol. HTTP is protocol well suited for use in a RESTful system. The API in question violates REST (atleast) by not using the methods provided by HTTP.

bobbyi 16y ago

GET is idempotent. It's fine if the first GET request to a resource has side effects (like creating it on demand).

rosser 16y ago

GET must never have side effects. POST, PUT, DELETE always have side effects. Pedantry: because they're supposed to be idempotent, POST, PUT, and DELETE should only have side-effects the first time they're issued against a given resource. Also, RFC 2616 uses "SHOULD NOT", as opposed to "MUST NOT" to describe the behavior of the "safe methods". To wit, "in particular, the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval."

cperciva 16y ago
POST is not idempotent. POST is explicitly what you should use for non-idempotent operations. This is why your web browser issues "need to resend a form" warnings when you return to earlier pages.
- rosser 16y ago
  Oops. Looks like, when I double-checked the RFC, my brain stuck POST in there. That'll show me for trying to be pedantic in the middle of doing thirteen other things. Thanks for the correction.
tmhedberg 16y ago
POST is not defined to be idempotent, although you're correct about PUT and DELETE.