Document the current behavior POST /{db}/_design/{ddoc}/_update/{func}/{docid}

[ecerulm]

Summary

The current documentation for 1.5.14. /{db}/_design/{ddoc}/_update/{func}/{docid} only mentions PUT method although POST also works

curl -v -n --json 'love'  http://couchdb.localhost:5984/hello-world/_design/recipe/_update/ingredients/SpaghettiWithMeatballs       
...
> POST /hello-world/_design/recipe/_update/ingredients/SpaghettiWithMeatballs HTTP/1.1
> Host: couchdb.localhost:5984
...
< HTTP/1.1 201 Created
...
< 
{"status":"ok"}

PUT is probably the preferred way, but I guess that POST should be also documented and probably deprecated too as @nickva mentioned in https://github.com/apache/couchdb/pull/4628#issuecomment-1570801221.

Desired Behaviour

Document POST /{db}/_design/{ddoc}/_update/{func}/{docid} with a deprecation note for next version.

Possible Solution

Additional context

This is just confusing for people like me that are new to CouchDB and like to go to the documentation as primary source.

If you see a code example somewhere in the internet using POST Document POST /{db}/_design/{ddoc}/_update/{func}/{docid}` and you go to the documentation to try to understand what is the purpose of that API call, you wouldn't find it. You would need to guess that probably POST and PUT do the same thing in this case.

Related

• https://github.com/apache/couchdb/pull/4628

[piyahub]

Hi, I would like to work on this issue.

I can update the documentation to include:

POST as a valid method for calling /{db}/_design/{ddoc}/_update/{func}/{docid}

A note that PUT is preferred

A note that POST may be deprecated in a future version

A small example showing POST usage

I will make this change in the appropriate API documentation section and open a PR. Please let me know if this approach looks correct.

Thanks!

[rnewson]

Hi @piyahub,

if there is something missing in the docs or could be improved, please go ahead and open a PR. We will discuss the changes there. You can find some contribution tips in our guide and I would like to draw particular attention to our prohibition of artificial intelligence.