apache / apache/couchdb

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

Open
#4,631 2 comments 0 reactions 0 assignees View on GitHub
beginner-friendly enhancement
Dominant language
Erlang
Stars
7k
Forks
1.1k
Avg merge
1d 16h
Merged PRs (30d)
9

Description

[NOTE]: # ( ^^ Provide a general summary of the request in the title above. ^^ )

## Summary

[NOTE]: # ( Provide a brief overview of what the new feature is all about. )

The current documentation for [1.5.14. /{db}/_design/{ddoc}/_update/{func}/{docid}](https://docs.couchdb.com/en/latest/api/ddoc/render.html#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

[NOTE]: # ( Tell us how the new feature should work. Be specific. )
[TIP]: # ( Do NOT give us access or passwords to your actual CouchDB! )

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

## Possible Solution

[NOTE]: # ( Not required. Suggest how to implement the addition or change. )

## Additional context

[TIP]: # ( Why does this feature matter to you? What unique circumstances do you have? )

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

Contributor guide

Open the contributing guide

Research direction

Open the current API documentation at docs.couchdb.com/en/latest/api/ddoc/render.html and locate the /{db}/_design/{ddoc}/_update/{func}/{docid} entry. Document that POST also works, include the requested deprecation note for the next version, and verify the wording against the related pull request and existing endpoint documentation.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.