Document Update Handler (update_doc) support for PUT and POST

[GoogleCodeExporter]

couchdb/client.py:
    def update_doc(self, name, docid=None, **options):
        """Calls server side update handler.

        :param name: the name of the update handler function in the format
                     ``designdoc/updatename``.
        :param docid: optional ID of a document to pass to the update handler.
        :param options: optional query string parameters.
        :return: (headers, body) tuple, where headers is a dict of headers
                 returned from the list function and body is a readable
                 file-like instance
        """
        path = _path_from_name(name, '_update')
        if docid is None:
            func = self.resource(*path).post
        else:
            path.append(docid)
            func = self.resource(*path).put
        _, headers, body = func(**options)
        return headers, body

The Document Update Handlers API reference 
(http://docs.couchdb.org/en/latest/ddocs.html#update-functions) mentions 
support for both PUT and POST. For larger updates (>650bytes) PUT is not 
appropriate (HTTP 414, request too long, concerns). The module should prefer 
POST or include a kwarg to allow the caller to decide the verb.

Thanks!

Original issue reported on code.google.com by te...@prosauce.org on 2 Oct 2013 at 11:23

[GoogleCodeExporter]

Actually, the update handlers supports any method except GET (that's artificial 
restriction on query server side).

However, semantically only POST and PUT methods matters and there is no any 
restrictions on their payload size. 

Is there some proxy-server in front of your CouchDB?

Original comment by kxepal on 3 Oct 2013 at 9:44

[GoogleCodeExporter]

Cool on the any method but GET comment, good to know! 

And cool on the no restriction on payload size. :) Regardless of my setup, you 
are right, objects are commonly length-restricted when proxies are used. Though 
there are additional concerns like request/access logging, which would prefer 
larger content in the body.

The issue does not reflect a specific setup, it is a common-practices 
suggestion. The flexibility of verb usage, by the caller, is desired. 

Thanks!

Original comment by te...@prosauce.org on 3 Oct 2013 at 2:03

[GoogleCodeExporter]

Suddenly, you have to fix your proxy setup because CouchDB uses RESTful HTTP 
API where request method's makes a sense. 

Fixing this issue for update handlers will not fix the similar for attachments 
- they are big and may be stored only with PUT method, so you will still have 
problems due to proxy server.

Original comment by kxepal on 3 Oct 2013 at 2:08

[GoogleCodeExporter]

I agree with you that PUT "traditionally" makes sense in a RESTful world to 
update objects (and POST to create). Forgive me if I'm asking you to commit 
RESTful sin by allowing an update with POST, haha. ;)

POST in some scenarios does make sense to update objects (i.e., I POST to add 
content, I POST to add sub-content, I POST a change). In this case, CouchDB 
supports POST to update documents via the Document Update Handler API. 

I'm not a web developer and admittedly not the person to argue/defend/describe 
REST implementations. Though I am a user of your module and would greatly 
appreciate mainline support that corroborates the CouchDB documentation. I've 
listed a few examples of why it may be preferred for some users. If they are 
not sufficient I am unfortunately at a loss.  

Original comment by te...@prosauce.org on 3 Oct 2013 at 2:22

[GoogleCodeExporter]

Sure, but I'm trying to tell you that fixing update_doc method for using POST 
method instead of PUT because you have proxy-server issues wouldn't help you 
with any other CouchDB API requests that required PUT-only requests like:

- Document updates
- Attachments storing
- Database security setup
- Replication
- On fly configuration updates

So this fix would be just a workaround of your network issues, not a fix of 
CouchDB API misusing.

Original comment by kxepal on 3 Oct 2013 at 2:50

[GoogleCodeExporter]

You're right, and in my case the issue is not the PUT vs. POST, but the 
handling of the expanded kwargs. 

The following seem equivalent:

PUT update_doc(..., body=options)
POST update_doc(..., **options)

PUT, with the expanded options tacks on the variables to the query string. 
POST, with the expanded options adds them as HTTP request content. Long request 
objects + query strings is trouble, long request contents is not.

My error is an oversight in the expected behavior of update_doc(..., 
**options). Since you're using POST and PUT (for new and updates respectively), 
there was some ambiguity about the behavior of the update variables. I'm not 
sure if this requires any action on the part of python-couchdb, though it would 
be nice if the API took the same action (updates within HTTP request body) when 
using update_doc.

Thanks! 

Original comment by te...@prosauce.org on 3 Oct 2013 at 4:17

[GoogleCodeExporter]

FWIW, I have a slightly different application that would benefit from being 
able to specify the method. As you say, the update handler will accept any 
method except for GET. Even though the documentation only mentions POST & PUT, 
COUCHDB-1779 describes using update handlers to implement PATCH until it is 
available as part of the CouchDB REST API. I'm working on a project where we 
will use DELETE against the update handler to flag a document as deleted, but 
otherwise preserve its contents (basically a Trash folder).

Original comment by jzy...@gmail.com on 15 Nov 2013 at 6:52

[GoogleCodeExporter]

This issue has been migrated to GitHub. Please continue discussion here:

https://github.com/djc/couchdb-python/issues/230

Original comment by djc.ochtman on 15 Jul 2014 at 7:23