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:11 UTC
(couchdb) 01/06: chore(docs): Add 403 status code to api docs
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 573e2008f0300cc1a1498d4d5b5be0b61df0cbef
Author: Ronny Berndt <ro...@apache.org>
AuthorDate: Fri Dec 27 15:32:28 2024 +0100
chore(docs): Add 403 status code to api docs
---
src/docs/src/api/basics.rst | 4 +-
src/docs/src/api/local.rst | 158 +++++++++++++++++++----------------
src/docs/src/api/partitioned-dbs.rst | 50 +++++++----
3 files changed, 126 insertions(+), 86 deletions(-)
diff --git a/src/docs/src/api/basics.rst b/src/docs/src/api/basics.rst
index bd29fb42c..3d5fba98a 100644
--- a/src/docs/src/api/basics.rst
+++ b/src/docs/src/api/basics.rst
@@ -551,9 +551,11 @@ specific request types are provided in the corresponding API call reference.
The item requested was not available using the supplied authorization, or
authorization was not supplied.
+.. _error/403:
+
- ``403 - Forbidden``
- The requested item or operation is forbidden. This might be because;
+ The requested item or operation is forbidden. This might be because:
* Your user name or roles do not match the security object of the database
* The request requires administrator privileges but you don't have them
diff --git a/src/docs/src/api/local.rst b/src/docs/src/api/local.rst
index 8d0cc914e..342d91ead 100644
--- a/src/docs/src/api/local.rst
+++ b/src/docs/src/api/local.rst
@@ -112,7 +112,10 @@ A list of the available methods and URL paths are provided below:
:>json number total_rows: Number of local 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>`
**Request**:
@@ -179,10 +182,14 @@ A list of the available methods and URL paths are provided below:
:synopsis: Returns a built-in view of all local (non-replicating) documents
in this database
- :method:`POST` `_local_docs` functionality supports identical parameters and behavior
+ :method:`POST` `/{db}/_local_docs` functionality supports identical parameters and behavior
as specified in the :get:`/{db}/_local_docs` API but allows for the query string
parameters to be supplied as keys in a JSON object in the body of the `POST` request.
+ :param db: Database name
+ :code 401: Unauthorized request to a protected API
+ :code 403: Insufficient permissions / :ref:`Too many requests with invalid credentials<error/403>`
+
**Request**:
.. code-block:: http
@@ -203,6 +210,8 @@ A list of the available methods and URL paths are provided below:
The returned JSON is the all documents structure, but with only the
selected keys in the output:
+ **Response**:
+
.. code-block:: javascript
{
@@ -259,82 +268,83 @@ A list of the available methods and URL paths are provided below:
: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**:
-
-.. code-block:: http
-
- POST /db/_local_docs/queries HTTP/1.1
- Content-Type: application/json
- Accept: application/json
- Host: localhost:5984
-
- {
- "queries": [
- {
- "keys": [
- "_local/localdoc05",
- "_local/not-exist",
- "_design/recipe",
- "spaghetti"
- ]
- }
- ]
- }
-
-**Response**:
-
-.. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Thu, 20 Jul 2023 21:45:37 GMT
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "results": [
- {
- "total_rows": null,
- "offset": null,
- "rows": [
- {
- "id": "_local/localdoc05",
- "key": "_local/localdoc05",
- "value": {
- "rev": "0-1"
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_local_docs/queries HTTP/1.1
+ Content-Type: application/json
+ Accept: application/json
+ Host: localhost:5984
+
+ {
+ "queries": [
+ {
+ "keys": [
+ "_local/localdoc05",
+ "_local/not-exist",
+ "_design/recipe",
+ "spaghetti"
+ ]
+ }
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Thu, 20 Jul 2023 21:45:37 GMT
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "results": [
+ {
+ "total_rows": null,
+ "offset": null,
+ "rows": [
+ {
+ "id": "_local/localdoc05",
+ "key": "_local/localdoc05",
+ "value": {
+ "rev": "0-1"
+ }
+ },
+ {
+ "key": "_local/not-exist",
+ "error": "not_found"
}
- },
- {
- "key": "_local/not-exist",
- "error": "not_found"
- }
- ]
- },
- {
- "total_rows": null,
- "offset": null,
- "rows": [
- {
- "id": "_local/localdoc04",
- "key": "_local/localdoc04",
- "value": {
- "rev": "0-1"
+ ]
+ },
+ {
+ "total_rows": null,
+ "offset": null,
+ "rows": [
+ {
+ "id": "_local/localdoc04",
+ "key": "_local/localdoc04",
+ "value": {
+ "rev": "0-1"
+ }
}
- }
- ]
- }
- ]
- }
+ ]
+ }
+ ]
+ }
-.. Note::
- Similar to :ref:`_design_docs/queries <api/db/_design_docs/queries>`,
- /{db}/_local_docs/queries will only return local documents.
- The difference is ``total_rows`` and ``offset`` are always ``null``.
+ .. Note::
+ Similar to :ref:`_design_docs/queries <api/db/_design_docs/queries>`,
+ /{db}/_local_docs/queries will only return local documents.
+ The difference is ``total_rows`` and ``offset`` are always ``null``.
.. _api/db/_local/doc:
@@ -348,6 +358,9 @@ A list of the available methods and URL paths are provided below:
a standard document in the specified database, except that the document is
not replicated. See :get:`/{db}/{docid}`.
+ :param db: Database name
+ :param docid: Document ID
+
.. http:put:: /{db}/_local/{docid}
:synopsis: Inserts a new version of the local document
@@ -355,6 +368,9 @@ A list of the available methods and URL paths are provided below:
a standard document in the specified database, except that the document is
not replicated. See :put:`/{db}/{docid}`.
+ :param db: Database name
+ :param docid: Document ID
+
.. http:delete:: /{db}/_local/{docid}
:synopsis: Deletes the local document
diff --git a/src/docs/src/api/partitioned-dbs.rst b/src/docs/src/api/partitioned-dbs.rst
index 1a280140f..00c0d62db 100644
--- a/src/docs/src/api/partitioned-dbs.rst
+++ b/src/docs/src/api/partitioned-dbs.rst
@@ -33,7 +33,12 @@ See the guide for
It includes document and deleted document counts along with external
and active data sizes.
+ :param db: Database name
+ :param partition_id: Name of the partition to query
+
: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**:
@@ -71,9 +76,6 @@ See the guide for
.. http:get:: /{db}/_partition/{partition_id}/_all_docs
:synopsis: Return all docs in the specified partition
- :param db: Database name
- :param partition_id: Partition name
-
This endpoint is a convenience endpoint for automatically setting
bounds on the provided partition range. Similar results can be had
by using the global ``/db/_all_docs`` endpoint with appropriately
@@ -83,6 +85,13 @@ See the guide for
a complete description of the available query parameters and the format
of the returned data.
+ :param db: Database name
+ :param partition_id: Partition name
+
+ :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**:
.. code-block:: http
@@ -125,11 +134,6 @@ See the guide for
.. http:get:: /{db}/_partition/{partition_id}/_design/{ddoc}/_view/{view}
:synopsis: Execute a partitioned query
- :param db: Database name
- :param partition_id: Partition name
- :param ddoc: Design document id
- :param view: View name
-
This endpoint is responsible for executing a partitioned query. The
returned view result will only contain rows with the specified
partition name.
@@ -138,6 +142,15 @@ See the guide for
a complete description of the available query parameters and the format
of the returned data.
+ :param db: Database name
+ :param partition_id: Partition name
+ :param ddoc: Design document id
+ :param view: View name
+
+ :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-block:: http
GET /db/_partition/sensor-260/_design/sensor-readings/_view/by_sensor HTTP/1.1
@@ -202,9 +215,6 @@ See the guide for
.. http:post:: /{db}/_partition/{partition_id}/_find
:synopsis: Query the partition specified by ``partition_id``
- :param db: Database name
- :param partition id: Name of the partition to query
-
This endpoint is responsible for finding a partition query by its ID.
The returned view result will only contain rows with the
specified partition id.
@@ -213,6 +223,14 @@ See the guide for
documentation for a complete description of the
available parameters and the format
of the returned data.
+
+ :param db: Database name
+ :param partition_id: Name of the partition to query
+
+ :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>`
+
.. _api/partitioned/explain:
``/{db}/_partition/{partition_id}/_explain``
@@ -221,11 +239,15 @@ See the guide for
.. http:post:: /{db}/_partition/{partition_id}/_explain
:synopsis: Find index that is used with a query
- :param db: Database name
- :partition id: Name of the partition to query
-
This endpoint shows which index is being used by the query.
Refer to the :ref:`explain endpoint <api/db/find/explain>`
documentation for a complete description of the available
parameters and the format of the returned data.
+
+ :param db: Database name
+ :param partition_id: Name of the partition to query
+
+ :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>`