You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ro...@apache.org on 2025/04/24 16:03:12 UTC
(couchdb) 02/06: chore(docs): Add HTTP status codes 401/403 to docs in api/database
This is an automated email from the ASF dual-hosted git repository.
ronny pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit e2f342f844516876f9c00277c3914f5e5752a7a5
Author: Ronny Berndt <ro...@apache.org>
AuthorDate: Sun Jan 5 13:50:42 2025 +0100
chore(docs): Add HTTP status codes 401/403 to docs in api/database
---
src/docs/src/api/database/bulk-api.rst | 325 +++++++++++++++++----------------
src/docs/src/api/database/changes.rst | 2 +
src/docs/src/api/database/cleanup.rst | 2 +
src/docs/src/api/database/common.rst | 5 +
src/docs/src/api/database/compact.rst | 5 +
src/docs/src/api/database/find.rst | 7 +
src/docs/src/api/database/misc.rst | 16 ++
src/docs/src/api/database/security.rst | 3 +
src/docs/src/api/database/shard.rst | 3 +
9 files changed, 213 insertions(+), 155 deletions(-)
diff --git a/src/docs/src/api/database/bulk-api.rst b/src/docs/src/api/database/bulk-api.rst
index fc31848dc..7b9fab764 100644
--- a/src/docs/src/api/database/bulk-api.rst
+++ b/src/docs/src/api/database/bulk-api.rst
@@ -29,7 +29,10 @@
:param db: Database name
:<header Content-Type: :mimetype:`application/json`
:>header Content-Type: - :mimetype:`application/json`
+
:code 200: Request completed successfully
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Requested database not found
**Request**:
@@ -203,7 +206,10 @@
:>json number total_rows: Number of design documents in the database. Note
that this is not the number of rows returned in the actual query.
:>json number update_seq: Current update sequence for the database
+
:code 200: Request completed successfully
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Requested database not found
**Request**:
@@ -295,6 +301,8 @@
The returned JSON is the all documents structure, but with only the
selected keys in the output:
+ **Response**:
+
.. code-block:: javascript
{
@@ -356,101 +364,102 @@ Sending multiple queries to a database
:code 200: Request completed successfully
:code 400: Invalid request
- :code 401: Read permission required
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Specified database is missing
:code 500: Query execution error
-**Request**:
+ **Request**:
-.. code-block:: http
+ .. code-block:: http
- POST /db/_all_docs/queries HTTP/1.1
- Content-Type: application/json
- Accept: application/json
- Host: localhost:5984
+ POST /db/_all_docs/queries HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+ Host: localhost:5984
- {
- "queries": [
- {
- "keys": [
- "meatballs",
- "spaghetti"
- ]
- },
- {
- "limit": 3,
- "skip": 2
- }
- ]
- }
+ {
+ "queries": [
+ {
+ "keys": [
+ "meatballs",
+ "spaghetti"
+ ]
+ },
+ {
+ "limit": 3,
+ "skip": 2
+ }
+ ]
+ }
-**Response**:
+ **Response**:
-.. code-block:: http
+ .. code-block:: http
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Wed, 20 Dec 2017 11:17:07 GMT
- ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Wed, 20 Dec 2017 11:17:07 GMT
+ ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
- {
- "results" : [
- {
- "rows": [
- {
- "id": "meatballs",
- "key": "meatballs",
- "value": 1
- },
- {
- "id": "spaghetti",
- "key": "spaghetti",
- "value": 1
- }
- ],
- "total_rows": 3
- },
- {
- "offset" : 2,
- "rows" : [
- {
- "id" : "Adukiandorangecasserole-microwave",
- "key" : "Aduki and orange casserole - microwave",
- "value" : [
- null,
- "Aduki and orange casserole - microwave"
- ]
- },
- {
- "id" : "Aioli-garlicmayonnaise",
- "key" : "Aioli - garlic mayonnaise",
- "value" : [
- null,
- "Aioli - garlic mayonnaise"
- ]
- },
- {
- "id" : "Alabamapeanutchicken",
- "key" : "Alabama peanut chicken",
- "value" : [
- null,
- "Alabama peanut chicken"
- ]
- }
- ],
- "total_rows" : 2667
- }
- ]
- }
+ {
+ "results" : [
+ {
+ "rows": [
+ {
+ "id": "meatballs",
+ "key": "meatballs",
+ "value": 1
+ },
+ {
+ "id": "spaghetti",
+ "key": "spaghetti",
+ "value": 1
+ }
+ ],
+ "total_rows": 3
+ },
+ {
+ "offset" : 2,
+ "rows" : [
+ {
+ "id" : "Adukiandorangecasserole-microwave",
+ "key" : "Aduki and orange casserole - microwave",
+ "value" : [
+ null,
+ "Aduki and orange casserole - microwave"
+ ]
+ },
+ {
+ "id" : "Aioli-garlicmayonnaise",
+ "key" : "Aioli - garlic mayonnaise",
+ "value" : [
+ null,
+ "Aioli - garlic mayonnaise"
+ ]
+ },
+ {
+ "id" : "Alabamapeanutchicken",
+ "key" : "Alabama peanut chicken",
+ "value" : [
+ null,
+ "Alabama peanut chicken"
+ ]
+ }
+ ],
+ "total_rows" : 2667
+ }
+ ]
+ }
-.. Note::
- The multiple queries are also supported in
- :ref:`/{db}/_local_docs/queries <api/db/_local_docs/queries>` and
- :ref:`/{db}/_design_docs/queries <api/db/_design_docs/queries>`
- (similar to :ref:`/{db}/_all_docs/queries <api/db/_all_docs/queries>`).
+ .. Note::
+ The multiple queries are also supported in
+ :ref:`/{db}/_local_docs/queries <api/db/_local_docs/queries>` and
+ :ref:`/{db}/_design_docs/queries <api/db/_design_docs/queries>`
+ (similar to :ref:`/{db}/_all_docs/queries <api/db/_all_docs/queries>`).
.. _api/db/_design_docs/queries:
@@ -485,69 +494,70 @@ Sending multiple queries to a database
:code 200: Request completed successfully
:code 400: Invalid request
- :code 401: Read permission required
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Specified database is missing
:code 500: Query execution error
-**Request**:
+ **Request**:
-.. code-block:: http
+ .. code-block:: http
- POST /db/_design_docs/queries HTTP/1.1
- Content-Type: application/json
- Accept: application/json
- Host: localhost:5984
+ POST /db/_design_docs/queries HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+ Host: localhost:5984
- {
- "queries": [
- {
- "keys": [
- "_design/recipe",
- "_design/not-exist",
- "spaghetti"
- ]
- }
- ]
- }
+ {
+ "queries": [
+ {
+ "keys": [
+ "_design/recipe",
+ "_design/not-exist",
+ "spaghetti"
+ ]
+ }
+ ]
+ }
-**Response**:
+ **Response**:
-.. code-block:: http
+ .. code-block:: http
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Thu, 20 Jul 2023 20:06:44 GMT
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Thu, 20 Jul 2023 20:06:44 GMT
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
- {
- "results": [
- {
- "total_rows": 1,
- "offset": null,
- "rows": [
- {
- "id": "_design/recipe",
- "key": "_design/recipe",
- "value": {
- "rev": "1-ad0e29fe6b473658514742a7c2317766"
+ {
+ "results": [
+ {
+ "total_rows": 1,
+ "offset": null,
+ "rows": [
+ {
+ "id": "_design/recipe",
+ "key": "_design/recipe",
+ "value": {
+ "rev": "1-ad0e29fe6b473658514742a7c2317766"
+ }
+ },
+ {
+ "key": "_design/not-exist",
+ "error": "not_found"
}
- },
- {
- "key": "_design/not-exist",
- "error": "not_found"
- }
- ]
- }
- ]
- }
+ ]
+ }
+ ]
+ }
-.. Note::
- /{db}/_design_docs/queries with keys will only return design documents,
- or ``"error": "not_found"`` if the design document doesn't exist. If
- ``key`` is not a design document id, it will not be included in the
- response.
+ .. Note::
+ /{db}/_design_docs/queries with keys will only return design documents,
+ or ``"error": "not_found"`` if the design document doesn't exist. If
+ ``key`` is not a design document id, it will not be included in the
+ response.
.. _api/db/bulk_get:
@@ -578,9 +588,11 @@ Sending multiple queries to a database
value describing the error, or ``ok`` key and associated value of the
requested document, with the additional ``_revisions`` property that lists
the parent revisions if ``revs=true``.
+
:code 200: Request completed successfully
:code 400: The request provided invalid JSON data or invalid query parameter
- :code 401: Read permission required
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Invalid database name
:code 415: Bad :header:`Content-Type` value
@@ -788,8 +800,11 @@ Sending multiple queries to a database
if document has saved without errors. *Optional*
:>jsonarr string error: Error type. *Optional*
:>jsonarr string reason: Error reason. *Optional*
+
:code 201: Document(s) have been created or updated
:code 400: The request provided invalid JSON data
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Requested database not found
**Request**:
@@ -1030,25 +1045,25 @@ supplying the new ``_rev`` parameter indicating a new document revision was
created. If the update failed, you will get an ``error`` of type ``conflict``.
For example:
- .. code-block:: javascript
-
- [
- {
- "id" : "FishStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- },
- {
- "id" : "LambStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- },
- {
- "id" : "BeefStew",
- "error" : "conflict",
- "reason" : "Document update conflict."
- }
- ]
+.. code-block:: javascript
+
+ [
+ {
+ "id" : "FishStew",
+ "error" : "conflict",
+ "reason" : "Document update conflict."
+ },
+ {
+ "id" : "LambStew",
+ "error" : "conflict",
+ "reason" : "Document update conflict."
+ },
+ {
+ "id" : "BeefStew",
+ "error" : "conflict",
+ "reason" : "Document update conflict."
+ }
+ ]
In this case no new revision has been created and you will need to submit the
document update, with the correct revision tag, to update the document.
diff --git a/src/docs/src/api/database/changes.rst b/src/docs/src/api/database/changes.rst
index b7d57855a..b52ee161a 100644
--- a/src/docs/src/api/database/changes.rst
+++ b/src/docs/src/api/database/changes.rst
@@ -136,6 +136,8 @@
:>json array results: Changes made to a database
:code 200: Request completed successfully
:code 400: Bad request
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
The ``results`` field of database changes:
diff --git a/src/docs/src/api/database/cleanup.rst b/src/docs/src/api/database/cleanup.rst
index ec397a69d..6193888e9 100644
--- a/src/docs/src/api/database/cleanup.rst
+++ b/src/docs/src/api/database/cleanup.rst
@@ -33,6 +33,7 @@
:code 202: Cleanup request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -78,6 +79,7 @@
:code 202: Cleanup request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
diff --git a/src/docs/src/api/database/common.rst b/src/docs/src/api/database/common.rst
index e726a1b94..bfc86118f 100644
--- a/src/docs/src/api/database/common.rst
+++ b/src/docs/src/api/database/common.rst
@@ -86,6 +86,8 @@
:>json boolean props.partitioned: (optional) If present and true, this
indicates that the database is partitioned.
:code 200: Request completed successfully
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Requested database not found
**Request**:
@@ -169,6 +171,7 @@
:code 202: Accepted (at least by one node)
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 412: Database already exists
**Request**:
@@ -271,6 +274,7 @@
:code 202: Accepted (deleted by at least one of the nodes, quorum is not met yet)
:code 400: Invalid database name or forgotten document id by accident
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Database doesn't exist or invalid database name
**Request**:
@@ -328,6 +332,7 @@
:code 202: Document data accepted, but not yet stored on disk
:code 400: Invalid database name
:code 401: Write privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Database doesn't exist
:code 409: A Conflicting Document with same ID already exists
diff --git a/src/docs/src/api/database/compact.rst b/src/docs/src/api/database/compact.rst
index ecd82b930..d52ffad80 100644
--- a/src/docs/src/api/database/compact.rst
+++ b/src/docs/src/api/database/compact.rst
@@ -54,6 +54,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 415: Bad :header:`Content-Type` value
**Request**:
@@ -107,6 +108,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Design document not found
:code 415: Bad :header:`Content-Type` value
@@ -167,6 +169,8 @@
:>json boolean ok: Operation status
:code 201: Commit completed successfully
:code 400: Invalid database name
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 415: Bad :header:`Content-Type` value
**Request**:
@@ -219,6 +223,7 @@
:code 202: Compaction request has been accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 415: Bad :header:`Content-Type` value
**Request**:
diff --git a/src/docs/src/api/database/find.rst b/src/docs/src/api/database/find.rst
index 011edf800..7f0d35de6 100644
--- a/src/docs/src/api/database/find.rst
+++ b/src/docs/src/api/database/find.rst
@@ -99,6 +99,7 @@
:code 200: Request completed successfully
:code 400: Invalid request
:code 401: Read permission required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Requested database not found
:code 500: Query execution error
@@ -370,6 +371,7 @@ built using MapReduce Views.
:code 200: Index created successfully or already exists
:code 400: Invalid request
:code 401: Admin permission required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Database not found
:code 500: Execution error
@@ -471,6 +473,7 @@ present, including those which have ``null`` values.
:code 200: Success
:code 400: Invalid request
:code 401: Read permission required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 500: Execution error
**Request**:
@@ -540,6 +543,7 @@ present, including those which have ``null`` values.
:code 200: Success
:code 400: Invalid request
:code 401: Writer permission required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Index not found
:code 500: Execution error
@@ -590,6 +594,8 @@ present, including those which have ``null`` values.
:code 200: Success
:code 400: Invalid request
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Requested database not found
:code 500: Execution error
@@ -683,6 +689,7 @@ present, including those which have ``null`` values.
:code 200: Request completed successfully
:code 400: Invalid request
:code 401: Read permission required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 500: Execution error
**Request**:
diff --git a/src/docs/src/api/database/misc.rst b/src/docs/src/api/database/misc.rst
index d2e974cdc..2124d94bc 100644
--- a/src/docs/src/api/database/misc.rst
+++ b/src/docs/src/api/database/misc.rst
@@ -48,6 +48,8 @@
:code 202: Request was accepted, and was completed successfully on at least
one replica, but quorum was not reached.
:code 400: Invalid database name or JSON payload
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 415: Bad :header:`Content-Type` value
:code 500: Internal server error or timeout
@@ -193,6 +195,8 @@ following behavior:
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
:code 400: Invalid database name
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -244,6 +248,8 @@ following behavior:
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -294,6 +300,8 @@ following behavior:
:>json boolean ok: Operation status
:code 200: Request completed successfully
:code 400: Invalid JSON data
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -346,6 +354,8 @@ following behavior:
revisions
:code 200: Request completed successfully
:code 400: Invalid database name or JSON payload
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -425,6 +435,8 @@ following behavior:
for specified document and its current revision in requested database
:code 200: Request completed successfully
:code 400: Invalid database name or JSON payload
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -485,6 +497,8 @@ following behavior:
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:code 200: Request completed successfully
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -525,6 +539,8 @@ following behavior:
:>json boolean ok: Operation status
:code 200: Request completed successfully
:code 400: Invalid JSON data
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
diff --git a/src/docs/src/api/database/security.rst b/src/docs/src/api/database/security.rst
index 57d676f77..a94363d7c 100644
--- a/src/docs/src/api/database/security.rst
+++ b/src/docs/src/api/database/security.rst
@@ -80,6 +80,8 @@
:>json object members: Object with two fields as ``names`` and ``roles``.
See description above for more info.
:code 200: Request completed successfully
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
@@ -138,6 +140,7 @@
:>json boolean ok: Operation status
:code 200: Request completed successfully
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
**Request**:
diff --git a/src/docs/src/api/database/shard.rst b/src/docs/src/api/database/shard.rst
index b9c196608..9cd7c6112 100644
--- a/src/docs/src/api/database/shard.rst
+++ b/src/docs/src/api/database/shard.rst
@@ -35,6 +35,7 @@
:code 200: Request completed successfully
:code 400: Invalid database name
:code 401: Read privilege required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 415: Bad :header:`Content-Type` value
:code 500: Internal server error or timeout
@@ -125,6 +126,7 @@
:>json array nodes: List of nodes serving a replica of the shard
:code 200: Request completed successfully
:code 401: Read privilege required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Database or document not found
:code 500: Internal server error or timeout
@@ -186,6 +188,7 @@
:code 202: Request accepted
:code 400: Invalid database name
:code 401: CouchDB Server Administrator privileges required
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
:code 404: Database not found
:code 500: Internal server error or timeout