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

[zooko]

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

[davidsarah]

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]

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

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

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

[davidsarah]

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.

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

[davidsarah]

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

(#1428 is invalid.)