Fix allowed method for ddoc update function

[jaydoane]

Overview

The semantics of PUT [1] are arguably incorrect for executing an update function on a specified document, since nothing is being created or updated. Also it's not clear why it would be different from the POST used for executing an update function for null document. [2]

Additionally, the example code-block in this section uses POST:

    POST /recipes/_design/recipe/_update/ingredients/SpaghettiWithMeatballs HTTP/1.1

All which lead me to believe that the PUT is a typo.

The actual behavior of CouchDB doesn't help here, since it currently accepts any method whatsoever:

$ curl -v -u adm localhost:15984/db-1/_design/ddoc/_update/change -X BOGUS

> BOGUS /db-1/_design/bar/_update/change HTTP/1.1
>
< HTTP/1.1 200 OK
< content-length: 11
< content-type: text/html; charset=utf-8
<
* Connection #0 to host localhost left intact
Empty World* Closing connection 0

[1] https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html [2] https://docs.couchdb.org/en/latest/api/ddoc/render.html#post--db-_design-ddoc-_update-func

Testing recommendations

GitHub issue number

Related Pull Requests

https://github.com/apache/couchdb/pull/3701

Checklist

• [ ] Update rebar.config.script with the commit hash once this PR is rebased and merged

[nickva]

POST is typically to create a subordinate sub-resource. So POST to $db with with a doc body would create a new document (sub-resource) in that $db.

PUT is to update an existing resource by specifying its full path. PUT to $db/$doc_id should update that $doc_id somehow, possibly replace it.

From https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html

The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database.

The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity. That resource might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server MUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI,

Could _update handlers also get PATCH or DELETE methods. Say if _updater handler removes the document?

[big-r81]

I'm closing this ticket due the migration of the docs from apache/couchdb-documentation to apache/couchdb. Please create a new PR in apache/couchdb.