#324 new defect

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

Reported by: zooko Owned by:
Priority: major Milestone: soon
Component: code-frontend-web Version: 0.8.0
Keywords: kpreid docs standards test http Cc: kpreid@…
Launchpad Bug:

Description

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

Change History (11)

comment:1 Changed at 2008-02-27T20:57:23Z by zooko

  • Cc kpreid@… added

comment:2 Changed at 2009-12-13T05:57:35Z by davidsarah

  • Keywords docs added

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?

comment:3 Changed at 2009-12-26T02:43:17Z by warner

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".

comment:4 Changed at 2010-02-27T08:40:57Z by davidsarah

  • Keywords standards added
  • Milestone changed from eventually to 1.7.0

comment:5 Changed at 2010-04-11T02:14:28Z by nejucomo

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.

comment:6 Changed at 2010-04-11T02:20:01Z by nejucomo

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.

comment:7 follow-up: Changed at 2010-04-11T02:33:58Z by davidsarah

  • Keywords test http added

For consistency with the existing POST /uri?... code (here), 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.

comment:8 in reply to: ↑ 7 Changed at 2010-04-11T02:41:28Z by davidsarah

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).

comment:9 Changed at 2010-06-16T03:55:53Z by davidsarah

  • Milestone changed from 1.7.0 to 1.7.1

comment:10 Changed at 2010-07-18T02:09:07Z by davidsarah

  • Milestone changed from 1.7.1 to soon

comment:11 Changed at 2011-07-12T23:58:39Z by davidsarah

  • Summary changed 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

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

(#1428 is invalid.)

Last edited at 2011-07-13T00:04:59Z by davidsarah (previous) (diff)
Note: See TracTickets for help on using tickets.