use POST for operations whose noun doesn't denote the same resource that a GET would denote, or that have side effects #324

New issue

Open

opened 2008-02-27 20:57:11 +00:00 by zooko · 7 comments

zooko commented

2008-02-27 20:57:11 +00:00

kpreid pointed out that using PUT <http://localhost:8123/uri> to PUT a file is wrong because GET on that same URL won't return that same file. We should use POST for things whose noun doesn't denote their resource, namely operations which don't also link the thing into a directory, i.e.:

 * PUT http://localhost:8123/uri
 * PUT http://localhost:8123/uri?mutable=true
 * PUT http://localhost:8123/uri?t=mkdir

kpreid pointed out that using `PUT <http://localhost:8123/uri>` to PUT a file is wrong because `GET` on that same URL won't return that same file. We should use `POST` for things whose noun doesn't denote their resource, namely operations which don't also link the thing into a directory, i.e.: ``` * PUT http://localhost:8123/uri * PUT http://localhost:8123/uri?mutable=true * PUT http://localhost:8123/uri?t=mkdir ```

zooko added the

labels 2008-02-27 20:57:11 +00:00

zooko added this to the eventually milestone 2008-02-27 20:57:11 +00:00

daira commented

2009-12-13 05:57:35 +00:00

For creating a directory, source:docs/frontends/webapi.txt#L343 says that 'The "PUT" operation is provided for backwards compatibility: new code should use POST.' There isn't any similar wording for files, though. Is this just a documentation bug, or is there code that needs to change?

warner commented

2009-12-26 02:43:17 +00:00

My understanding of REST is that POST is for side-effecty things (and is frequently used to effectively send a message to the resource named by the URL), PUT is for creating new resources in a specific place, and GET is for retrieving those resources from that specific place. Uploading new files is side-effecty and creates a new resource, but not in a specific place. So I guess "POST /uri" is probably a reasonable immutable-upload operation, and we should stop using "PUT /uri".

I haven't thought through it carefully. PUT seems like a good verb for uploading a file, but certainly "PUT /uri" doesn't correspond to "GET /uri" (since "GET /uri" isn't even legal). "PUT /uri/DIRCAP/filename" would match "GET /uri/DIRCAP/filename", so I think that's ok. My understanding of REST is that POST is for side-effecty things (and is frequently used to effectively send a message to the resource named by the URL), PUT is for creating new resources in a specific place, and GET is for retrieving those resources from that specific place. Uploading new files is side-effecty and creates a new resource, but not in a specific place. So I guess "POST /uri" is probably a reasonable immutable-upload operation, and we should stop using "PUT /uri".

daira modified the milestone from eventually to 1.7.0

2010-02-27 08:40:57 +00:00

nejucomo commented

2010-04-11 02:14:28 +00:00

As of 1.6.1 there is already an existing POST /uri handler. For the case of files it requires a t=upload parameter and the response is suitable for browsers (either html or an HTTP redirection).

Tangentially there appears to be a convention where some POST operations accept an output=json parameter.

So, davidsarah and nejucomo propose adding a handler for POST /uri?output=json. This should be backwards compatible to existing clients, but solves the issue raised in this ticket.

As of 1.6.1 there is already an existing `POST /uri` handler. For the case of files it requires a `t=upload` parameter and the response is suitable for browsers (either html or an HTTP redirection). Tangentially there appears to be a convention where some `POST` operations accept an `output=json` parameter. So, davidsarah and nejucomo propose adding a handler for `POST /uri?output=json`. This should be backwards compatible to existing clients, but solves the issue raised in this ticket.

nejucomo commented

2010-04-11 02:20:01 +00:00

This ticket raises a design consistency issue, but I want to point out a practical issue:

As of 1.6.1 it's not easy to use python urllib2 to publish an unlinked file or directory. It cannot do PUT out-of-the-box (maybe possible by creating custom request handlers). Meanwhile the only output options for POST /uri?t=upload are html or an HTTP redirect. urllib2 transparently follows redirects, so this leaves html scraping or custom urllib2 request handlers as the alternatives.

Now that that is clearer it might be time to switch to httplib.

This ticket raises a design consistency issue, but I want to point out a practical issue: As of 1.6.1 it's not easy to use python `urllib2` to publish an unlinked file or directory. It cannot do `PUT` out-of-the-box (maybe possible by creating custom request handlers). Meanwhile the only output options for `POST /uri?t=upload` are html or an HTTP redirect. `urllib2` transparently follows redirects, so this leaves html scraping or custom urllib2 request handlers as the alternatives. Now that that is clearer it might be time to switch to httplib.

daira commented

2010-04-11 02:33:58 +00:00

For consistency with the existing POST /uri?... code ([here]source:src/allmydata/web/root.py?rev=4238#L64), both POST /uri?output=json and POST /uri?t=upload&output=json would be allowed with the same meaning.

The specification for this operation needs to say what the output JSON looks like. I would suggest it should be exactly like the output of GET $FILECAP?t=json for the resulting file.

Slightly off-topic for this ticket, but switching to httplib for the CLI commands would also make it easier to fix #965, IIUC.

For consistency with the existing `POST /uri?...` code ([here]source:src/allmydata/web/root.py?rev=4238#L64), both `POST /uri?output=json` and `POST /uri?t=upload&output=json` would be allowed with the same meaning. The specification for this operation needs to say what the output JSON looks like. I would suggest it should be exactly like the output of `GET $FILECAP?t=json` for the resulting file. Slightly off-topic for this ticket, but switching to httplib for the CLI commands would also make it easier to fix #965, IIUC.

daira commented

2010-04-11 02:41:28 +00:00

Replying to davidsarah:

Slightly off-topic for this ticket, but switching to httplib for the CLI commands would also make it easier to fix #965, IIUC.

Oh, I'm not making sense. The CLI commands already use httplib; it is changing them to use urllib2 that would make #965 easier (and that is definitely off-topic here).

Replying to [davidsarah](/tahoe-lafs/trac/issues/324#issuecomment-365750): > Slightly off-topic for this ticket, but switching to httplib for the CLI commands would also make it easier to fix #965, IIUC. Oh, I'm not making sense. The CLI commands already use `httplib`; it is changing them to use `urllib2` that would make #965 easier (and that is definitely off-topic here).

daira modified the milestone from 1.7.0 to 1.7.1

2010-06-16 03:55:53 +00:00

daira modified the milestone from 1.7.1 to soon

2010-07-18 02:09:07 +00:00

daira commented

2011-07-12 23:58:39 +00:00

~~Similar to #1428, but not quite the same issue.~~

(#1428 is invalid.)

~~Similar to #1428, but not quite the same issue.~~ (#1428 is invalid.)

daira changed title from ~~use POST for operations whose noun doesn't denote the same resource that a GET would denote~~ to use POST for operations whose noun doesn't denote the same resource that a GET would denote, or that have side effects