You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2015/02/20 01:26:53 UTC
[20/26] documentation commit: updated refs/heads/master to 5a81ace
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/src/api/database/misc.rst b/src/api/database/misc.rst
index 194dac3..20c8aa0 100644
--- a/src/api/database/misc.rst
+++ b/src/api/database/misc.rst
@@ -10,342 +10,339 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/db/purge:
+==============
``/db/_purge``
==============
.. http:post:: /{db}/_purge
- :synopsis: Purges some historical documents entirely from database history
-
- A database purge permanently removes the references to deleted documents
- from the database. Normal deletion of a document within CouchDB does not
- remove the document from the database, instead, the document is marked as
- ``_deleted=true`` (and a new revision is created). This is to ensure that
- deleted documents can be replicated to other databases as having been
- deleted. This also means that you can check the status of a document and
- identify that the document has been deleted by its absence.
-
- .. warning::
-
- Purging a document from a database should only be done as a last resort
- when sensitive information has been introduced inadvertently into a
- database. In clustered or replicated environments it is very difficult
- to guarantee that a particular purged document has been removed from all
- replicas. Do not rely on this API as a way of doing secure deletion.
-
- The purge operation removes the references to the deleted documents from
- the database. The purging of old documents is not replicated to other
- databases. If you are replicating between databases and have deleted a
- large number of documents you should run purge on each database.
-
- .. note::
-
- Purging documents does not remove the space used by them on disk. To
- reclaim disk space, you should run a database compact (see
- :ref:`api/db/compact`), and compact views (see :ref:`api/db/compact/ddoc`).
-
- The format of the request must include the document ID and one or more
- revisions that must be purged.
-
- The response will contain the purge sequence number, and a list of the
- document IDs and revisions successfully purged.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object: Mapping of document ID to list of revisions to purge
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json number purge_seq: Purge sequence number
- :>json object purged: Mapping of document ID to list of purged revisions
- :code 200: Request completed successfully
- :code 400: Invalid database name or JSON payload
- :code 415: Bad :header:`Content-Type` value
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_purge HTTP/1.1
- Accept: application/json
- Content-Length: 76
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
- "3-0e871ef78849b0c206091f1a7af6ec41"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 103
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "purge_seq":3,
- "purged":{
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
- ]
- }
- }
-
+ :synopsis: Purges some historical documents entirely from database history
+
+ A database purge permanently removes the references to deleted documents
+ from the database. Normal deletion of a document within CouchDB does not
+ remove the document from the database, instead, the document is marked as
+ ``_deleted=true`` (and a new revision is created). This is to ensure that
+ deleted documents can be replicated to other databases as having been
+ deleted. This also means that you can check the status of a document and
+ identify that the document has been deleted by its absence.
+
+ .. warning::
+ Purging a document from a database should only be done as a last resort
+ when sensitive information has been introduced inadvertently into a
+ database. In clustered or replicated environments it is very difficult
+ to guarantee that a particular purged document has been removed from
+ all replicas. Do not rely on this API as a way of doing secure
+ deletion.
+
+ The purge operation removes the references to the deleted documents from
+ the database. The purging of old documents is not replicated to other
+ databases. If you are replicating between databases and have deleted a
+ large number of documents you should run purge on each database.
+
+ .. note::
+ Purging documents does not remove the space used by them on disk. To
+ reclaim disk space, you should run a database compact (see
+ :ref:`api/db/compact`), and compact views
+ (see :ref:`api/db/compact/ddoc`).
+
+ The format of the request must include the document ID and one or more
+ revisions that must be purged.
+
+ The response will contain the purge sequence number, and a list of the
+ document IDs and revisions successfully purged.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<json object: Mapping of document ID to list of revisions to purge
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json number purge_seq: Purge sequence number
+ :>json object purged: Mapping of document ID to list of purged revisions
+ :code 200: Request completed successfully
+ :code 400: Invalid database name or JSON payload
+ :code 415: Bad :header:`Content-Type` value
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_purge HTTP/1.1
+ Accept: application/json
+ Content-Length: 76
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
+ "3-0e871ef78849b0c206091f1a7af6ec41"
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 103
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 10:53:24 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "purge_seq":3,
+ "purged":{
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
+ ]
+ }
+ }
Updating Indexes
-----------------
+================
-The number of purges on a database is tracked using a purge sequence.
-This is used by the view indexer to optimize the updating of views that
-contain the purged documents.
+The number of purges on a database is tracked using a purge sequence. This is
+used by the view indexer to optimize the updating of views that contain the
+purged documents.
-When the indexer identifies that the purge sequence on a database has
-changed, it compares the purge sequence of the database with that stored
-in the view index. If the difference between the stored sequence and
-database is sequence is only 1, then the indexer uses a cached list of
-the most recently purged documents, and then removes these documents
-from the index individually. This prevents completely rebuilding the
-index from scratch.
-
-If the difference between the stored sequence number and current
-database sequence is greater than 1, then the view index is entirely
-rebuilt. This is an expensive operation as every document in the
-database must be examined.
+When the indexer identifies that the purge sequence on a database has changed,
+it compares the purge sequence of the database with that stored in the view
+index. If the difference between the stored sequence and database is sequence
+is only 1, then the indexer uses a cached list of the most recently purged
+documents, and then removes these documents from the index individually. This
+prevents completely rebuilding the index from scratch.
+If the difference between the stored sequence number and current database
+sequence is greater than 1, then the view index is entirely rebuilt. This is
+an expensive operation as every document in the database must be examined.
.. _api/db/missing_revs:
+=====================
``/db/_missing_revs``
=====================
.. http:post:: /{db}/_missing_revs
- :synopsis: By given list of document revisions returns the document revisions that do not exist in the database
-
- With given a list of document revisions, returns the document revisions that
- do not exist in the database.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object: Mapping of document ID to list of revisions to lookup
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json object missing_revs: Mapping of document ID to list of missed revisions
- :code 200: Request completed successfully
- :code 400: Invalid database name or JSON payload
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_missing_revs HTTP/1.1
- Accept: application/json
- Content-Length: 76
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
- "3-0e871ef78849b0c206091f1a7af6ec41"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 64
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 10:53:24 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "missed_revs":{
- "c6114c65e295552ab1019e2b046b10e": [
- "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
- ]
- }
- }
-
+ :synopsis: By given list of document revisions returns the document revisions that do not exist in the database
+
+ With given a list of document revisions, returns the document revisions
+ that do not exist in the database.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<json object: Mapping of document ID to list of revisions to lookup
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json object missing_revs: Mapping of document ID to list of missed
+ revisions
+ :code 200: Request completed successfully
+ :code 400: Invalid database name or JSON payload
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_missing_revs HTTP/1.1
+ Accept: application/json
+ Content-Length: 76
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
+ "3-0e871ef78849b0c206091f1a7af6ec41"
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 64
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 10:53:24 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "missed_revs":{
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
+ ]
+ }
+ }
.. _api/db/revs_diff:
+==================
``/db/_revs_diff``
==================
.. http:post:: /{db}/_revs_diff
- :synopsis: By given list of document revisions returns differences between the given revisions and ones that are in the database
-
- Given a set of document/revision IDs, returns the subset of those that do
- not correspond to revisions stored in the database.
-
- Its primary use is by the replicator, as an important optimization: after
- receiving a set of new revision IDs from the source database, the replicator
- sends this set to the destination database's ``_revs_diff`` to find out which
- of them already exist there. It can then avoid fetching and sending
- already-known document bodies.
-
- Both the request and response bodies are JSON objects whose keys are document
- IDs; but the values are structured differently:
-
- - In the request, a value is an array of revision IDs for that document.
-
- - In the response, a value is an object with a ``missing``: key, whose value
- is a list of revision IDs for that document (the ones that are not stored
- in the database) and optionally a ``possible_ancestors`` key, whose value is
- an array of revision IDs that are known that might be ancestors of
- the missing revisions.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object: Mapping of document ID to list of revisions to lookup
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json array missing: List of missed revisions for specified document
- :>json array possible_ancestors: List of revisions that *may be* ancestors
- for specified document and its current revision in requested database
- :code 200: Request completed successfully
- :code 400: Invalid database name or JSON payload
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_revs_diff HTTP/1.1
- Accept: application/json
- Content-Length: 113
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "190f721ca3411be7aa9477db5f948bbb": [
- "3-bb72a7682290f94a985f7afac8b27137",
- "4-10265e5a26d807a3cfa459cf1a82ef2e",
- "5-067a00dff5e02add41819138abb3284d"
- ]
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 88
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 16:56:02 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "190f721ca3411be7aa9477db5f948bbb": {
- "missing": [
- "3-bb72a7682290f94a985f7afac8b27137",
- "5-067a00dff5e02add41819138abb3284d"
- ],
- "possible_ancestors": [
- "4-10265e5a26d807a3cfa459cf1a82ef2e"
- ]
- }
- }
-
+ :synopsis: By given list of document revisions returns differences between the given revisions and ones that are in the database
+
+ Given a set of document/revision IDs, returns the subset of those that do
+ not correspond to revisions stored in the database.
+
+ Its primary use is by the replicator, as an important optimization: after
+ receiving a set of new revision IDs from the source database, the
+ replicator sends this set to the destination database's ``_revs_diff`` to
+ find out which of them already exist there. It can then avoid fetching and
+ sending already-known document bodies.
+
+ Both the request and response bodies are JSON objects whose keys are
+ document IDs; but the values are structured differently:
+
+ - In the request, a value is an array of revision IDs for that document.
+
+ - In the response, a value is an object with a ``missing``: key, whose
+ value is a list of revision IDs for that document (the ones that are not
+ stored in the database) and optionally a ``possible_ancestors`` key,
+ whose value is an array of revision IDs that are known that might be
+ ancestors of the missing revisions.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<json object: Mapping of document ID to list of revisions to lookup
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json array missing: List of missed revisions for specified document
+ :>json array possible_ancestors: List of revisions that *may be* ancestors
+ for specified document and its current revision in requested database
+ :code 200: Request completed successfully
+ :code 400: Invalid database name or JSON payload
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_revs_diff HTTP/1.1
+ Accept: application/json
+ Content-Length: 113
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "190f721ca3411be7aa9477db5f948bbb": [
+ "3-bb72a7682290f94a985f7afac8b27137",
+ "4-10265e5a26d807a3cfa459cf1a82ef2e",
+ "5-067a00dff5e02add41819138abb3284d"
+ ]
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 88
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 16:56:02 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "190f721ca3411be7aa9477db5f948bbb": {
+ "missing": [
+ "3-bb72a7682290f94a985f7afac8b27137",
+ "5-067a00dff5e02add41819138abb3284d"
+ ],
+ "possible_ancestors": [
+ "4-10265e5a26d807a3cfa459cf1a82ef2e"
+ ]
+ }
+ }
.. _api/db/revs_limit:
+===================
``/db/_revs_limit``
===================
.. http:get:: /{db}/_revs_limit
- :synopsis: Returns the limit of historical revisions to store for a single document in the database
-
- Gets the current ``revs_limit`` (revision limit) setting.
+ :synopsis: Returns the limit of historical revisions to store for a single document in the database
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :code 200: Request completed successfully
+ Gets the current ``revs_limit`` (revision limit) setting.
- **Request**:
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :code 200: Request completed successfully
- .. code-block:: http
+ **Request**:
- GET /db/_revs_limit HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ .. code-block:: http
- **Response**:
+ GET /db/_revs_limit HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- .. code-block:: http
+ **Response**:
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 5
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 17:27:30 GMT
- Server: CouchDB (Erlang/OTP)
+ .. code-block:: http
- 1000
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 5
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 17:27:30 GMT
+ Server: CouchDB (Erlang/OTP)
+ 1000
.. http:put:: /{db}/_revs_limit
- :synopsis: Sets the limit of historical revisions to store for a single document in the database
+ :synopsis: Sets the limit of historical revisions to store for a single document in the database
- Sets the maximum number of document revisions that will be tracked by
- CouchDB, even after compaction has occurred. You can set the revision
- limit on a database with a scalar integer of the limit that you want
- to set as the request body.
+ Sets the maximum number of document revisions that will be tracked by
+ CouchDB, even after compaction has occurred. You can set the revision limit
+ on a database with a scalar integer of the limit that you want to set as
+ the request body.
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 200: Request completed successfully
- :code 400: Invalid JSON data
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json boolean ok: Operation status
+ :code 200: Request completed successfully
+ :code 400: Invalid JSON data
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- PUT /db/_revs_limit HTTP/1.1
- Accept: application/json
- Content-Length: 5
- Content-Type: application/json
- Host: localhost:5984
+ PUT /db/_revs_limit HTTP/1.1
+ Accept: application/json
+ Content-Length: 5
+ Content-Type: application/json
+ Host: localhost:5984
- 1000
+ 1000
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 17:47:52 GMT
- Server: CouchDB (Erlang/OTP)
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 17:47:52 GMT
+ Server: CouchDB (Erlang/OTP)
- {
- "ok": true
- }
+ {
+ "ok": true
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/security.rst
----------------------------------------------------------------------
diff --git a/src/api/database/security.rst b/src/api/database/security.rst
index 3757133..4775d9b 100644
--- a/src/api/database/security.rst
+++ b/src/api/database/security.rst
@@ -10,173 +10,174 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/db/security:
+=================
``/db/_security``
=================
.. http:get:: /{db}/_security
- :synopsis: Returns the special security object for the database
-
- Returns the current security object from the specified database.
-
- The security object consists of two compulsory elements, ``admins``
- and ``members``, which are used to specify the list of users and/or roles
- that have admin and members rights to the database respectively:
-
- - ``members``: they can read all types of documents from the DB, and they can
- write (and edit) documents to the DB except for design documents.
-
- - ``admins``: they have all the privileges of ``members`` plus the privileges:
- write (and edit) design documents, add/remove database admins and members,
- set the :ref:`database revisions limit <api/db/revs_limit>` and execute
- :ref:`temporary views <api/db/temp_view>` against the database.
- They can not create a database nor delete a database.
-
- Both ``members`` and ``admins`` objects are contains two array-typed fields:
-
- - ``users``: List of CouchDB user names
- - ``roles``: List of users roles
-
- Any other additional fields in the security object are optional.
- The entire security object is made available to validation and other
- internal functions so that the database can control and limit functionality.
-
- If both the names and roles fields of either the admins or members properties
- are empty arrays, it means the database has no admins or members.
-
- Having no admins, only server admins (with the reserved ``_admin`` role)
- are able to update design document and make other admin level changes.
-
- Having no members, any user can write regular documents (any non-design
- document) and read documents from the database.
-
- If there are any member names or roles defined for a database, then only
- authenticated users having a matching name or role are allowed to
- read documents from the database (or do a :get:`/{db}` call).
-
- .. note::
-
- If the security object for a database has never been set, then the
- value returned will be empty.
-
- Also note, that security objects are not regular versioned documents
- (that is, they are not under MVCC rules). This is a design choice to
- speedup authorization checks (avoids traversing a database`s documents
- B-Tree).
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json object admins: Object with two fields as ``names`` and ``roles``.
- See description above for more info.
- :>json object members: Object with two fields as ``names`` and ``roles``.
- See description above for more info.
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/_security HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 109
- Content-Type: application/json
- Date: Mon, 12 Aug 2013 19:05:29 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "admins": {
- "names": [
- "superuser"
- ],
- "roles": [
- "admins"
- ]
- },
- "members": {
- "names": [
- "user1",
- "user2"
- ],
- "roles": [
- "developers"
- ]
+ :synopsis: Returns the special security object for the database
+
+ Returns the current security object from the specified database.
+
+ The security object consists of two compulsory elements, ``admins``
+ and ``members``, which are used to specify the list of users and/or roles
+ that have admin and members rights to the database respectively:
+
+ - ``members``: they can read all types of documents from the DB, and they
+ can write (and edit) documents to the DB except for design documents.
+
+ - ``admins``: they have all the privileges of ``members`` plus the
+ privileges: write (and edit) design documents, add/remove database admins
+ and members, set the :ref:`database revisions limit <api/db/revs_limit>`
+ and execute :ref:`temporary views <api/db/temp_view>` against the
+ database. They can not create a database nor delete a database.
+
+ Both ``members`` and ``admins`` objects are contains two array-typed
+ fields:
+
+ - ``users``: List of CouchDB user names
+ - ``roles``: List of users roles
+
+ Any other additional fields in the security object are optional.
+ The entire security object is made available to validation and other
+ internal functions so that the database can control and limit
+ functionality.
+
+ If both the names and roles fields of either the admins or members
+ properties are empty arrays, it means the database has no admins or
+ members.
+
+ Having no admins, only server admins (with the reserved ``_admin`` role)
+ are able to update design document and make other admin level changes.
+
+ Having no members, any user can write regular documents (any non-design
+ document) and read documents from the database.
+
+ If there are any member names or roles defined for a database, then only
+ authenticated users having a matching name or role are allowed to read
+ documents from the database (or do a :get:`/{db}` call).
+
+ .. note::
+ If the security object for a database has never been set, then the
+ value returned will be empty.
+
+ Also note, that security objects are not regular versioned documents
+ (that is, they are not under MVCC rules). This is a design choice to
+ speedup authorization checks (avoids traversing a database`s documents
+ B-Tree).
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json object admins: Object with two fields as ``names`` and ``roles``.
+ See description above for more info.
+ :>json object members: Object with two fields as ``names`` and ``roles``.
+ See description above for more info.
+ :code 200: Request completed successfully
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /db/_security HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 109
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 19:05:29 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "admins": {
+ "names": [
+ "superuser"
+ ],
+ "roles": [
+ "admins"
+ ]
+ },
+ "members": {
+ "names": [
+ "user1",
+ "user2"
+ ],
+ "roles": [
+ "developers"
+ ]
+ }
}
- }
-
.. http:put:: /{db}/_security
- :synopsis: Sets the special security object for the database
-
- Sets the security object for the given database.
-
- :param db: Database name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :<header Content-Type: :mimetype:`application/json`
- :<json object admins: Object with two fields as ``names`` and ``roles``.
- :ref:`See description above for more info <api/db/security>`.
- :<json object members: Object with two fields as ``names`` and ``roles``.
- :ref:`See description above for more info <api/db/security>`.
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json boolean ok: Operation status
- :code 200: Request completed successfully
- :code 401: CouchDB Server Administrator privileges required
-
- **Request**:
-
- .. code-block:: http
-
- PUT /db/_security HTTP/1.1
- Accept: application/json
- Content-Length: 121
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "admins": {
- "names": [
- "superuser"
- ],
- "roles": [
- "admins"
- ]
- },
- "members": {
- "names": [
- "user1",
- "user2"
- ],
- "roles": [
- "developers"
- ]
+ :synopsis: Sets the special security object for the database
+
+ Sets the security object for the given database.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<json object admins: Object with two fields as ``names`` and ``roles``.
+ :ref:`See description above for more info <api/db/security>`.
+ :<json object members: Object with two fields as ``names`` and ``roles``.
+ :ref:`See description above for more info <api/db/security>`.
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json boolean ok: Operation status
+ :code 200: Request completed successfully
+ :code 401: CouchDB Server Administrator privileges required
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /db/_security HTTP/1.1
+ Accept: application/json
+ Content-Length: 121
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "admins": {
+ "names": [
+ "superuser"
+ ],
+ "roles": [
+ "admins"
+ ]
+ },
+ "members": {
+ "names": [
+ "user1",
+ "user2"
+ ],
+ "roles": [
+ "developers"
+ ]
+ }
}
- }
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 11:26:28 GMT
- Server: CouchDB (Erlang/OTP)
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 12
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 11:26:28 GMT
+ Server: CouchDB (Erlang/OTP)
- {
- "ok": true
- }
+ {
+ "ok": true
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/database/temp-views.rst
----------------------------------------------------------------------
diff --git a/src/api/database/temp-views.rst b/src/api/database/temp-views.rst
index 2888e3a..447da0c 100644
--- a/src/api/database/temp-views.rst
+++ b/src/api/database/temp-views.rst
@@ -10,70 +10,70 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/db/temp_view:
+==================
``/db/_temp_view``
==================
.. http:post:: /{db}/_temp_view
- :synopsis: Executes a given view function for all documents and returns the result
-
- Creates (and executes) a temporary view based on the view function
- supplied in the JSON request.
-
- The arguments also available to standard view requests also apply to
- temporary views, but the execution of the view may take some time as it
- relies on being executed at the time of the request. This means that for
- every temporary view you create, the entire database will be read
- one doc at a time and passed through the view function.
-
- This should not be used on production CouchDB instances, and is purely a
- convenience function for quick development testing. You should use a
- defined view if you want to achieve the best performance.
-
- See :ref:`api/ddoc/view` for more info.
-
- **Request**:
-
- .. code-block:: http
-
- POST /db/_temp_view?group=true HTTP/1.1
- Accept: application/json
- Content-Length: 92
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "map": "function(doc) { if (doc.value) { emit(doc.value, null); } }",
- "reduce": "_count"
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Type: application/json
- Date: Tue, 13 Aug 2013 12:28:12 GMT
- ETag: "AU33B3N7S9K4SAZSFA048HVB4"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
-
- {
- "rows": [
- {
- "key": -10,
- "value": 1
- },
- {
- "key": 10,
- "value": 2
- },
- {
- "key": 15,
- "value": 1
- }
- ]
- }
+ :synopsis: Executes a given view function for all documents and returns the result
+
+ Creates (and executes) a temporary view based on the view function
+ supplied in the JSON request.
+
+ The arguments also available to standard view requests also apply to
+ temporary views, but the execution of the view may take some time as it
+ relies on being executed at the time of the request. This means that for
+ every temporary view you create, the entire database will be read
+ one doc at a time and passed through the view function.
+
+ This should not be used on production CouchDB instances, and is purely a
+ convenience function for quick development testing. You should use a
+ defined view if you want to achieve the best performance.
+
+ See :ref:`api/ddoc/view` for more info.
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db/_temp_view?group=true HTTP/1.1
+ Accept: application/json
+ Content-Length: 92
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "map": "function(doc) { if (doc.value) { emit(doc.value, null); } }",
+ "reduce": "_count"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 12:28:12 GMT
+ ETag: "AU33B3N7S9K4SAZSFA048HVB4"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
+
+ {
+ "rows": [
+ {
+ "key": -10,
+ "value": 1
+ },
+ {
+ "key": 10,
+ "value": 2
+ },
+ {
+ "key": 15,
+ "value": 1
+ }
+ ]
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/src/api/ddoc/common.rst b/src/api/ddoc/common.rst
index b3eecb6..dfc4fd6 100644
--- a/src/api/ddoc/common.rst
+++ b/src/api/ddoc/common.rst
@@ -10,201 +10,190 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/ddoc:
+==========================
``/db/_design/design-doc``
==========================
.. http:head:: /{db}/_design/{ddoc}
- :synopsis: Returns bare information in the HTTP Headers for the design document
-
- Returns the HTTP Headers containing a minimal amount of information
- about the specified design document.
+ :synopsis: Returns bare information in the HTTP Headers for the design document
- .. seealso::
-
- :head:`/{db}/{docid}`
+ Returns the HTTP Headers containing a minimal amount of information about
+ the specified design document.
+ .. seealso::
+ :head:`/{db}/{docid}`
.. http:get:: /{db}/_design/{ddoc}
- :synopsis: Returns the design document
-
- Returns the contents of the design document specified with the name of the design
- document and from the specified database from the URL. Unless you request a specific
- revision, the latest revision of the document will always be returned.
-
- .. seealso::
+ :synopsis: Returns the design document
- :get:`/{db}/{docid}`
+ Returns the contents of the design document specified with the name of the
+ design document and from the specified database from the URL. Unless you
+ request a specific revision, the latest revision of the document will
+ always be returned.
+ .. seealso::
+ :get:`/{db}/{docid}`
.. http:put:: /{db}/_design/{ddoc}
- :synopsis: Creates a new design document or new version of an existing one
-
- The :method:`PUT` method creates a new named design document, or creates
- a new revision of the existing design document.
-
- The design documents have some agreement upon their fields and structure.
- Currently it is the following:
-
- * **language** (*string*): Defines :ref:`Query Server <query-server>`
- :config:section:`key <query_servers>` to process design document functions
- * **options** (*object*): View's default options
- * **filters** (*object*): :ref:`Filter functions <filterfun>` definition
- * **lists** (*object*): :ref:`List functions <listfun>` definition
- * **rewrites** (*array*): Rewrite rules definition
- * **shows** (*object*): :ref:`Show functions <showfun>` definition
- * **updates** (*object*): :ref:`Update functions <updatefun>` definition
- * **validate_doc_update** (*string*): :ref:`Validate document update <vdufun>`
- function source
- * **views** (*object*): :ref:`View functions <viewfun>` definition.
-
- Note, that for ``filters``, ``lists``, ``shows`` and ``updates`` fields
- objects are mapping of function name to string function source code.
- For ``views`` mapping is the same except that values are objects with ``map``
- and ``reduce`` (optional) keys which also contains functions source code.
-
- .. seealso::
-
- :put:`/{db}/{docid}`
-
+ :synopsis: Creates a new design document or new version of an existing one
+
+ The :method:`PUT` method creates a new named design document, or creates
+ a new revision of the existing design document.
+
+ The design documents have some agreement upon their fields and structure.
+ Currently it is the following:
+
+ * **language** (*string*): Defines :ref:`Query Server <query-server>`
+ :config:section:`key <query_servers>` to process design document
+ functions
+ * **options** (*object*): View's default options
+ * **filters** (*object*): :ref:`Filter functions <filterfun>` definition
+ * **lists** (*object*): :ref:`List functions <listfun>` definition
+ * **rewrites** (*array*): Rewrite rules definition
+ * **shows** (*object*): :ref:`Show functions <showfun>` definition
+ * **updates** (*object*): :ref:`Update functions <updatefun>` definition
+ * **validate_doc_update** (*string*): :ref:`Validate document update
+ <vdufun>` function source
+ * **views** (*object*): :ref:`View functions <viewfun>` definition.
+
+ Note, that for ``filters``, ``lists``, ``shows`` and ``updates`` fields
+ objects are mapping of function name to string function source code. For
+ ``views`` mapping is the same except that values are objects with ``map``
+ and ``reduce`` (optional) keys which also contains functions source code.
+
+ .. seealso::
+ :put:`/{db}/{docid}`
.. http:delete:: /{db}/_design/{ddoc}
- :synopsis: Deletes the design document
-
- Deletes the specified document from the database. You must supply the
- current (latest) revision, either by using the ``rev`` parameter to
- specify the revision.
+ :synopsis: Deletes the design document
- .. seealso::
+ Deletes the specified document from the database. You must supply the
+ current (latest) revision, either by using the ``rev`` parameter to
+ specify the revision.
- :delete:`/{db}/{docid}`
+ .. seealso::
+ :delete:`/{db}/{docid}`
.. http:copy:: /{db}/_design/{ddoc}
- :synopsis: Copies the design document
-
- The :method:`COPY` (which is non-standard HTTP) copies an existing
- design document to a new or existing one.
+ :synopsis: Copies the design document
- .. note::
- Copying a design document does automatically reconstruct the view
- indexes. These will be recreated, as with other views, the first
- time the new view is accessed.
+ The :method:`COPY` (which is non-standard HTTP) copies an existing design
+ document to a new or existing one.
- .. seealso::
-
- :copy:`/{db}/{docid}`
+ .. note::
+ Copying a design document does automatically reconstruct the view
+ indexes. These will be recreated, as with other views, the first time
+ the new view is accessed.
+ .. seealso::
+ :copy:`/{db}/{docid}`
.. _api/ddoc/attachment:
+=====================================
``/db/_design/design-doc/attachment``
=====================================
.. http:head:: /{db}/_design/{ddoc}/{attname}
- :synopsis: Returns bare information in the HTTP Headers for the attachment
-
- Returns the HTTP headers containing a minimal amount of information
- about the specified attachment.
+ :synopsis: Returns bare information in the HTTP Headers for the attachment
- .. seealso::
+ Returns the HTTP headers containing a minimal amount of information about
+ the specified attachment.
- :head:`/{db}/{docid}/{attname}`
+ .. seealso::
+ :head:`/{db}/{docid}/{attname}`
.. http:get:: /{db}/_design/{ddoc}/{attname}
- :synopsis: Gets the attachment of a design document
+ :synopsis: Gets the attachment of a design document
- Returns the file attachment associated with the design document.
- The raw data of the associated attachment is returned (just as if you were
- accessing a static file.
+ Returns the file attachment associated with the design document. The raw
+ data of the associated attachment is returned (just as if you were
+ accessing a static file.
- .. seealso::
-
- :get:`/{db}/{docid}/{attname}`
+ .. seealso::
+ :get:`/{db}/{docid}/{attname}`
.. http:put:: /{db}/_design/{ddoc}/{attname}
- :synopsis: Adds an attachment of a design document
-
- Uploads the supplied content as an attachment to the specified design
- document. The attachment name provided must be a URL encoded string.
+ :synopsis: Adds an attachment of a design document
- .. seealso::
+ Uploads the supplied content as an attachment to the specified design
+ document. The attachment name provided must be a URL encoded string.
- :put:`/{db}/{docid}/{attname}`
+ .. seealso::
+ :put:`/{db}/{docid}/{attname}`
.. http:delete:: /{db}/_design/{ddoc}/{attname}
- :synopsis: Deletes an attachment of a design document
-
- Deletes the attachment of the specified design document.
+ :synopsis: Deletes an attachment of a design document
- .. seealso::
-
- :delete:`/{db}/{docid}/{attname}`
+ Deletes the attachment of the specified design document.
+ .. seealso::
+ :delete:`/{db}/{docid}/{attname}`
.. _api/ddoc/info:
+================================
``/db/_design/design-doc/_info``
================================
.. http:get:: /{db}/_design/{ddoc}/_info
- :synopsis: Returns view index information for the specified design document
-
- Obtains information about the specified design document, including the index,
- index size and current status of the design document and associated
- index information.
-
- :param db: Database name
- :param ddoc: Design document name
- :<header Accept: - :mimetype:`application/json`
- - :mimetype:`text/plain`
- :>header Content-Type: - :mimetype:`application/json`
- - :mimetype:`text/plain; charset=utf-8`
- :>json string name: Design document name
- :>json object view_index: :ref:`api/ddoc/view_index_info`
- :code 200: Request completed successfully
-
- **Request**:
-
- .. code-block:: http
-
- GET /recipes/_design/recipe/_info HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 263
- Content-Type: application/json
- Date: Sat, 17 Aug 2013 12:54:17 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "name": "recipe",
- "view_index": {
- "compact_running": false,
- "data_size": 926691,
- "disk_size": 1982704,
- "language": "python",
- "purge_seq": 0,
- "signature": "a59a1bb13fdf8a8a584bc477919c97ac",
- "update_seq": 12397,
- "updater_running": false,
- "waiting_clients": 0,
- "waiting_commit": false
+ :synopsis: Returns view index information for the specified design document
+
+ Obtains information about the specified design document, including the
+ index, index size and current status of the design document and associated
+ index information.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>json string name: Design document name
+ :>json object view_index: :ref:`api/ddoc/view_index_info`
+ :code 200: Request completed successfully
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/_design/recipe/_info HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 263
+ Content-Type: application/json
+ Date: Sat, 17 Aug 2013 12:54:17 GMT
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "name": "recipe",
+ "view_index": {
+ "compact_running": false,
+ "data_size": 926691,
+ "disk_size": 1982704,
+ "language": "python",
+ "purge_seq": 0,
+ "signature": "a59a1bb13fdf8a8a584bc477919c97ac",
+ "update_seq": 12397,
+ "updater_running": false,
+ "waiting_clients": 0,
+ "waiting_commit": false
+ }
}
- }
-
.. _api/ddoc/view_index_info:
View Index Information
-----------------------
+======================
The response from :get:`/{db}/_design/{ddoc}/_info` contains
``view_index`` (*object*) field with the next structure:
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/ddoc/index.rst
----------------------------------------------------------------------
diff --git a/src/api/ddoc/index.rst b/src/api/ddoc/index.rst
index 20e6740..1d704d8 100644
--- a/src/api/ddoc/index.rst
+++ b/src/api/ddoc/index.rst
@@ -10,28 +10,25 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/design-docs:
================
Design Documents
================
-In CouchDB, design documents provide the main interface for building a
-CouchDB application. The design document defines the views used to
-extract information from CouchDB through one or more views. Design
-documents are created within your CouchDB instance in the same way as
-you create database documents, but the content and definition of the
-documents is different. Design Documents are named using an ID defined
-with the design document URL path, and this URL can then be used to
-access the database contents.
+In CouchDB, design documents provide the main interface for building a CouchDB
+application. The design document defines the views used to extract information
+from CouchDB through one or more views. Design documents are created within
+your CouchDB instance in the same way as you create database documents, but the
+content and definition of the documents is different. Design Documents are
+named using an ID defined with the design document URL path, and this URL can
+then be used to access the database contents.
-Views and lists operate together to provide automated (and formatted)
-output from your database.
+Views and lists operate together to provide automated (and formatted) output
+from your database.
.. toctree::
-
- common
- views
- render
- rewrites
+ common
+ views
+ render
+ rewrites
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/ddoc/render.rst
----------------------------------------------------------------------
diff --git a/src/api/ddoc/render.rst b/src/api/ddoc/render.rst
index 84c25c2..e38875c 100644
--- a/src/api/ddoc/render.rst
+++ b/src/api/ddoc/render.rst
@@ -10,379 +10,386 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/ddoc/show:
+==========================================
``/db/_design/design-doc/_show/show-name``
==========================================
.. http:get:: /{db}/_design/{ddoc}/_show/{func}
- :synopsis: Executes a show function against null document
+ :synopsis: Executes a show function against null document
.. http:post:: /{db}/_design/{ddoc}/_show/{func}
- :synopsis: Same as GET method for the related endpoint
+ :synopsis: Same as GET method for the related endpoint
- Applies :ref:`show function <showfun>` for `null` document.
+ Applies :ref:`show function <showfun>` for `null` document.
- The request and response parameters are depended upon function implementation.
+ The request and response parameters are depended upon function
+ implementation.
- :param db: Database name
- :param ddoc: Design document name
- :param func: Show function name
- :>header ETag: Response signature
- :query string format: Format of the returned response.
- Used by :js:func:`provides` function
- :code 200: Request completed successfully
- :code 500: Query server error
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Show function name
+ :>header ETag: Response signature
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
- **Function**:
+ **Function**:
- .. code-block:: javascript
+ .. code-block:: javascript
- function(doc, req) {
- if (!doc) {
- return {body: "no doc"}
- } else {
- return {body: doc.description}
- }
- }
+ function(doc, req) {
+ if (!doc) {
+ return {body: "no doc"}
+ } else {
+ return {body: doc.description}
+ }
+ }
- **Request**:
+ **Request**:
- .. code-block:: http
+ .. code-block:: http
- GET /recipes/_design/recipe/_show/description HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/_design/recipe/_show/description HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- **Response**:
+ **Response**:
- .. code-block:: http
+ .. code-block:: http
- HTTP/1.1 200 OK
- Content-Length: 6
- Content-Type: text/html; charset=utf-8
- Date: Wed, 21 Aug 2013 12:34:07 GMT
- Etag: "7Z2TO7FPEMZ0F4GH0RJCRIOAU"
- Server: CouchDB (Erlang/OTP)
- Vary: Accept
-
- no doc
+ HTTP/1.1 200 OK
+ Content-Length: 6
+ Content-Type: text/html; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:34:07 GMT
+ Etag: "7Z2TO7FPEMZ0F4GH0RJCRIOAU"
+ Server: CouchDB (Erlang/OTP)
+ Vary: Accept
+ no doc
.. _api/ddoc/show/id:
+=================================================
``/db/_design/design-doc/_show/show-name/doc-id``
=================================================
.. http:get:: /{db}/_design/{ddoc}/_show/{func}/{docid}
- :synopsis: Executes a show function against the specified document
-.. http:post:: /{db}/_design/{ddoc}/_show/{func}/{docid}
- :synopsis: Same as GET method for the related endpoint
+ :synopsis: Executes a show function against the specified document
- Applies :ref:`show function <showfun>` for the specified document.
+.. http:post:: /{db}/_design/{ddoc}/_show/{func}/{docid}
+ :synopsis: Same as GET method for the related endpoint
- The request and response parameters are depended upon function implementation.
+ Applies :ref:`show function <showfun>` for the specified document.
- :param db: Database name
- :param ddoc: Design document name
- :param func: Show function name
- :param docid: Document ID
- :>header ETag: Response signature
- :query string format: Format of the returned response.
- Used by :js:func:`provides` function
- :code 200: Request completed successfully
- :code 500: Query server error
+ The request and response parameters are depended upon function
+ implementation.
- **Function**:
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Show function name
+ :param docid: Document ID
+ :>header ETag: Response signature
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
- .. code-block:: javascript
+ **Function**:
- function(doc, req) {
- if (!doc) {
- return {body: "no doc"}
- } else {
- return {body: doc.description}
- }
- }
+ .. code-block:: javascript
- **Request**:
+ function(doc, req) {
+ if (!doc) {
+ return {body: "no doc"}
+ } else {
+ return {body: doc.description}
+ }
+ }
- .. code-block:: http
+ **Request**:
- GET /recipes/_design/recipe/_show/description/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ .. code-block:: http
- **Response**:
+ GET /recipes/_design/recipe/_show/description/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- .. code-block:: http
+ **Response**:
- HTTP/1.1 200 OK
- Content-Length: 88
- Content-Type: text/html; charset=utf-8
- Date: Wed, 21 Aug 2013 12:38:08 GMT
- Etag: "8IEBO8103EI98HDZL5Z4I1T0C"
- Server: CouchDB (Erlang/OTP)
- Vary: Accept
+ .. code-block:: http
- An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.
+ HTTP/1.1 200 OK
+ Content-Length: 88
+ Content-Type: text/html; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:38:08 GMT
+ Etag: "8IEBO8103EI98HDZL5Z4I1T0C"
+ Server: CouchDB (Erlang/OTP)
+ Vary: Accept
+ An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.
.. _api/ddoc/list:
+====================================================
``/db/_design/design-doc/_list/list-name/view-name``
====================================================
.. http:get:: /{db}/_design/{ddoc}/_list/{func}/{view}
- :synopsis: Executes a list function against the view from the same design document
-.. http:post:: /{db}/_design/{ddoc}/_list/{func}/{view}
- :synopsis: Same as GET method for the related endpoint
+ :synopsis: Executes a list function against the view from the same design document
- Applies :ref:`list function <listfun>` for the :ref:`view function <viewfun>`
- from the same design document.
+.. http:post:: /{db}/_design/{ddoc}/_list/{func}/{view}
+ :synopsis: Same as GET method for the related endpoint
- The request and response parameters are depended upon function implementation.
+ Applies :ref:`list function <listfun>` for the :ref:`view function
+ <viewfun>` from the same design document.
- :param db: Database name
- :param ddoc: Design document name
- :param func: List function name
- :param view: View function name
- :>header ETag: Response signature
- :>header Transfer-Encoding: ``chunked``
- :query string format: Format of the returned response.
- Used by :js:func:`provides` function
- :code 200: Request completed successfully
- :code 500: Query server error
+ The request and response parameters are depended upon function
+ implementation.
- **Function**:
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: List function name
+ :param view: View function name
+ :>header ETag: Response signature
+ :>header Transfer-Encoding: ``chunked``
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
- .. code-block:: javascript
+ **Function**:
- function(head, req) {
- var row = getRow();
- if (!row){
- return 'no ingredients'
- }
- send(row.key);
- while(row=getRow()){
- send(', ' + row.key);
- }
- }
+ .. code-block:: javascript
- **Request**:
+ function(head, req) {
+ var row = getRow();
+ if (!row){
+ return 'no ingredients'
+ }
+ send(row.key);
+ while(row=getRow()){
+ send(', ' + row.key);
+ }
+ }
- .. code-block:: http
+ **Request**:
- GET /recipes/_design/recipe/_list/ingredients/by_name HTTP/1.1
- Accept: text/plain
- Host: localhost:5984
+ .. code-block:: http
- **Response**:
+ GET /recipes/_design/recipe/_list/ingredients/by_name HTTP/1.1
+ Accept: text/plain
+ Host: localhost:5984
- .. code-block:: http
+ **Response**:
- HTTP/1.1 200 OK
- Content-Type: text/plain; charset=utf-8
- Date: Wed, 21 Aug 2013 12:49:15 GMT
- Etag: "D52L2M1TKQYDD1Y8MEYJR8C84"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
- Vary: Accept
+ .. code-block:: http
- meatballs, spaghetti, tomato sauce
+ HTTP/1.1 200 OK
+ Content-Type: text/plain; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:49:15 GMT
+ Etag: "D52L2M1TKQYDD1Y8MEYJR8C84"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
+ Vary: Accept
+ meatballs, spaghetti, tomato sauce
.. _api/ddoc/list/ddoc:
+===============================================================
``/db/_design/design-doc/_list/list-name/other-ddoc/view-name``
===============================================================
.. http:get:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
- :synopsis: Executes a list function against the view from other design document
-.. http:post:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
- :synopsis: Same as GET method for the related endpoint
+ :synopsis: Executes a list function against the view from other design document
- Applies :ref:`list function <listfun>` for the :ref:`view function <viewfun>`
- from the other design document.
+.. http:post:: /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}
+ :synopsis: Same as GET method for the related endpoint
- The request and response parameters are depended upon function implementation.
+ Applies :ref:`list function <listfun>` for the :ref:`view function
+ <viewfun>` from the other design document.
- :param db: Database name
- :param ddoc: Design document name
- :param func: List function name
- :param other-ddoc: Other design document name that holds view function
- :param view: View function name
- :>header ETag: Response signature
- :>header Transfer-Encoding: ``chunked``
- :query string format: Format of the returned response.
- Used by :js:func:`provides` function
- :code 200: Request completed successfully
- :code 500: Query server error
+ The request and response parameters are depended upon function
+ implementation.
- **Function**:
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: List function name
+ :param other-ddoc: Other design document name that holds view function
+ :param view: View function name
+ :>header ETag: Response signature
+ :>header Transfer-Encoding: ``chunked``
+ :query string format: Format of the returned response.
+ Used by :js:func:`provides` function
+ :code 200: Request completed successfully
+ :code 500: Query server error
- .. code-block:: javascript
+ **Function**:
- function(head, req) {
- var row = getRow();
- if (!row){
- return 'no ingredients'
- }
- send(row.key);
- while(row=getRow()){
- send(', ' + row.key);
- }
- }
+ .. code-block:: javascript
- **Request**:
+ function(head, req) {
+ var row = getRow();
+ if (!row){
+ return 'no ingredients'
+ }
+ send(row.key);
+ while(row=getRow()){
+ send(', ' + row.key);
+ }
+ }
- .. code-block:: http
+ **Request**:
- GET /recipes/_design/ingredient/_list/ingredients/recipe/by_ingredient?key="spaghetti" HTTP/1.1
- Accept: text/plain
- Host: localhost:5984
+ .. code-block:: http
- **Response**:
+ GET /recipes/_design/ingredient/_list/ingredients/recipe/by_ingredient?key="spaghetti" HTTP/1.1
+ Accept: text/plain
+ Host: localhost:5984
- .. code-block:: http
+ **Response**:
- HTTP/1.1 200 OK
- Content-Type: text/plain; charset=utf-8
- Date: Wed, 21 Aug 2013 12:49:15 GMT
- Etag: "5L0975X493R0FB5Z3043POZHD"
- Server: CouchDB (Erlang/OTP)
- Transfer-Encoding: chunked
- Vary: Accept
+ .. code-block:: http
- spaghetti
+ HTTP/1.1 200 OK
+ Content-Type: text/plain; charset=utf-8
+ Date: Wed, 21 Aug 2013 12:49:15 GMT
+ Etag: "5L0975X493R0FB5Z3043POZHD"
+ Server: CouchDB (Erlang/OTP)
+ Transfer-Encoding: chunked
+ Vary: Accept
+ spaghetti
.. _api/ddoc/update:
+==============================================
``/db/_design/design-doc/_update/update-name``
==============================================
.. http:post:: /{db}/_design/{ddoc}/_update/{func}
- :synopsis: Executes an update function against the null document
-
- Executes :ref:`update function <updatefun>` on server side for ``null``
- document.
+ :synopsis: Executes an update function against the null document
- :param db: Database name
- :param ddoc: Design document name
- :param func: Update function name
- :>header X-Couch-Id: Created/updated document's ID
- :>header X-Couch-Update-NewRev: Created/updated document's revision
- :code 200: No document was created or updated
- :code 201: Document was created or updated
- :code 500: Query server error
+ Executes :ref:`update function <updatefun>` on server side for ``null``
+ document.
- **Function**:
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Update function name
+ :>header X-Couch-Id: Created/updated document's ID
+ :>header X-Couch-Update-NewRev: Created/updated document's revision
+ :code 200: No document was created or updated
+ :code 201: Document was created or updated
+ :code 500: Query server error
- .. code-block:: javascript
+ **Function**:
- function(doc, req) {
- if (!doc){
- return [null, {'code': 400,
- 'json': {'error': 'missed',
- 'reason': 'no document to update'}}]
- } else {
- doc.ingredients.push(req.body);
- return [doc, {'json': {'status': 'ok'}}];
- }
- }
+ .. code-block:: javascript
- **Request**:
+ function(doc, req) {
+ if (!doc){
+ return [null, {'code': 400,
+ 'json': {'error': 'missed',
+ 'reason': 'no document to update'}}]
+ } else {
+ doc.ingredients.push(req.body);
+ return [doc, {'json': {'status': 'ok'}}];
+ }
+ }
- .. code-block:: http
+ **Request**:
- POST /recipes/_design/recipe/_update/ingredients HTTP/1.1
- Accept: application/json
- Content-Length: 10
- Content-Type: application/json
- Host: localhost:5984
+ .. code-block:: http
- something
+ POST /recipes/_design/recipe/_update/ingredients HTTP/1.1
+ Accept: application/json
+ Content-Length: 10
+ Content-Type: application/json
+ Host: localhost:5984
- **Response**:
+ something
- .. code-block:: http
+ **Response**:
- HTTP/1.1 404 Object Not Found
- Cache-Control: must-revalidate
- Content-Length: 52
- Content-Type: application/json
- Date: Wed, 21 Aug 2013 14:00:58 GMT
- Server: CouchDB (Erlang/OTP)
+ .. code-block:: http
- {
- "error": "missed",
- "reason": "no document to update"
- }
+ HTTP/1.1 404 Object Not Found
+ Cache-Control: must-revalidate
+ Content-Length: 52
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 14:00:58 GMT
+ Server: CouchDB (Erlang/OTP)
+ {
+ "error": "missed",
+ "reason": "no document to update"
+ }
.. _api/ddoc/update/id:
+=====================================================
``/db/_design/design-doc/_update/update-name/doc-id``
=====================================================
.. http:put:: /{db}/_design/{ddoc}/_update/{func}/{docid}
- :synopsis: Executes an update function against the specified document
-
- Executes :ref:`update function <updatefun>` on server side for the specified
- document.
-
- :param db: Database name
- :param ddoc: Design document name
- :param func: Update function name
- :param docid: Document ID
- :>header X-Couch-Id: Created/updated document's ID
- :>header X-Couch-Update-NewRev: Created/updated document's revision
- :code 200: No document was created or updated
- :code 201: Document was created or updated
- :code 500: Query server error
-
- **Function**:
-
- .. code-block:: javascript
-
- function(doc, req) {
- if (!doc){
- return [null, {'code': 400,
- 'json': {'error': 'missed',
- 'reason': 'no document to update'}}]
- } else {
- doc.ingredients.push(req.body);
- return [doc, {'json': {'status': 'ok'}}];
- }
- }
-
- **Request**:
-
- .. code-block:: http
-
- POST /recipes/_design/recipe/_update/ingredients/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- Content-Length: 5
- Content-Type: application/json
- Host: localhost:5984
-
- love
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 16
- Content-Type: application/json
- Date: Wed, 21 Aug 2013 14:11:34 GMT
- Server: CouchDB (Erlang/OTP)
- X-Couch-Id: SpaghettiWithMeatballs
- X-Couch-Update-NewRev: 12-a5e099df5720988dae90c8b664496baf
-
- {
- "status": "ok"
- }
+ :synopsis: Executes an update function against the specified document
+
+ Executes :ref:`update function <updatefun>` on server side for the specified
+ document.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :param func: Update function name
+ :param docid: Document ID
+ :>header X-Couch-Id: Created/updated document's ID
+ :>header X-Couch-Update-NewRev: Created/updated document's revision
+ :code 200: No document was created or updated
+ :code 201: Document was created or updated
+ :code 500: Query server error
+
+ **Function**:
+
+ .. code-block:: javascript
+
+ function(doc, req) {
+ if (!doc){
+ return [null, {'code': 400,
+ 'json': {'error': 'missed',
+ 'reason': 'no document to update'}}]
+ } else {
+ doc.ingredients.push(req.body);
+ return [doc, {'json': {'status': 'ok'}}];
+ }
+ }
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /recipes/_design/recipe/_update/ingredients/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 5
+ Content-Type: application/json
+ Host: localhost:5984
+
+ love
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 16
+ Content-Type: application/json
+ Date: Wed, 21 Aug 2013 14:11:34 GMT
+ Server: CouchDB (Erlang/OTP)
+ X-Couch-Id: SpaghettiWithMeatballs
+ X-Couch-Update-NewRev: 12-a5e099df5720988dae90c8b664496baf
+
+ {
+ "status": "ok"
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/ddoc/rewrites.rst
----------------------------------------------------------------------
diff --git a/src/api/ddoc/rewrites.rst b/src/api/ddoc/rewrites.rst
index 90abddd..e67770e 100644
--- a/src/api/ddoc/rewrites.rst
+++ b/src/api/ddoc/rewrites.rst
@@ -10,81 +10,82 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/ddoc/rewrite:
+========================================
``/db/_design/design-doc/_rewrite/path``
========================================
.. http:any:: /{db}/_design/{ddoc}/_rewrite/{path}
- :synopsis: Rewrites HTTP request for the specified path by using stored routing rules
-
- Rewrites the specified path by rules defined in the specified design document.
-
- The rewrite rules are defined in *array* field of the design document called
- ``rewrites``. Each rule is an *object* with next structure:
-
- - **from** (*string*): The path rule used to bind current uri to the rule.
- It use pattern matching for that
- - **to** (*string*): Rule to rewrite an url. It can contain variables
- depending on binding variables discovered during pattern matching and
- query args (url args and from the query member)
- - **method** (*string*): HTTP request method to bind the request method to
- the rule. Default is ``"*"``
- - **query** (*object*): Query args you want to define they can contain
- dynamic variable by binding the key
-
- The ``to``and ``from`` paths may contains string patterns with leading ``:``
- or ``*`` characters.
-
- For example: ``/somepath/:var/*``
-
- - This path is converted in Erlang list by splitting ``/``
- - Each ``var`` are converted in atom
- - ``""`` are converted to ``''`` atom
- - The pattern matching is done by splitting ``/`` in request url in a list of
- token
- - A string pattern will match equal token
- - The star atom (``'*'`` in single quotes) will match any number of tokens,
- but may only be present as the last `pathterm` in a `pathspec`
- - If all tokens are matched and all `pathterms` are used, then the `pathspec`
- matches
-
- The pattern matching is done by first matching the HTTP request method to a
- rule. ``method`` is equal to ``"*"`` by default, and will match any HTTP
- method. It will then try to match the path to one rule. If no rule matches,
- then a :statuscode:`404` response returned.
-
- Once a rule is found we rewrite the request url using the ``to`` and ``query``
- fields. The identified token are matched to the rule and will replace var.
- If ``'*'`` is found in the rule it will contain the remaining part if it
- exists.
-
- Examples:
-
- +--------------------------------------+----------+------------------+-------+
- | Rule | Url | Rewrite to | Tokens|
- +======================================+==========+==================+=======+
- | {"from": "/a", "to": "/some"} | /a | /some | |
- +--------------------------------------+----------+------------------+-------+
- | {"from": "/a/\*", "to": "/some/\*} | /a/b/c | /some/b/c | |
- +--------------------------------------+----------+------------------+-------+
- | {"from": "/a/b", "to": "/some"} | /a/b?k=v | /some?k=v | k=v |
- +--------------------------------------+----------+------------------+-------+
- | {"from": "/a/b", "to": "/some/:var"} | /a/b | /some/b?var=b | var=b |
- +--------------------------------------+----------+------------------+-------+
- | {"from": "/a/:foo/", | /a/b/c | /some/b/c?foo=b | foo=b |
- | "to": "/some/:foo/"} | | | |
- +--------------------------------------+----------+------------------+-------+
- | {"from": "/a/:foo", "to": "/some", | /a/b | /some/?k=b&foo=b | foo=b |
- | "query": { "k": ":foo" }} | | | |
- +--------------------------------------+----------+------------------+-------+
- | {"from": "/a", "to": "/some/:foo"} | /a?foo=b | /some/?b&foo=b | foo=b |
- +--------------------------------------+----------+------------------+-------+
-
- Request method, header, query parameters, request payload and response body
- are depended on endpoint to which url will be rewritten.
-
- :param db: Database name
- :param ddoc: Design document name
- :param path: URL path to rewrite
+ :synopsis: Rewrites HTTP request for the specified path by using stored routing rules
+
+ Rewrites the specified path by rules defined in the specified design
+ document.
+
+ The rewrite rules are defined in *array* field of the design document
+ called ``rewrites``. Each rule is an *object* with next structure:
+
+ - **from** (*string*): The path rule used to bind current uri to the rule.
+ It use pattern matching for that
+ - **to** (*string*): Rule to rewrite an url. It can contain variables
+ depending on binding variables discovered during pattern matching and
+ query args (url args and from the query member)
+ - **method** (*string*): HTTP request method to bind the request method to
+ the rule. Default is ``"*"``
+ - **query** (*object*): Query args you want to define they can contain
+ dynamic variable by binding the key
+
+ The ``to``and ``from`` paths may contains string patterns with leading
+ ``:`` or ``*`` characters.
+
+ For example: ``/somepath/:var/*``
+
+ - This path is converted in Erlang list by splitting ``/``
+ - Each ``var`` are converted in atom
+ - ``""`` are converted to ``''`` atom
+ - The pattern matching is done by splitting ``/`` in request url in a list
+ of token
+ - A string pattern will match equal token
+ - The star atom (``'*'`` in single quotes) will match any number of tokens,
+ but may only be present as the last `pathterm` in a `pathspec`
+ - If all tokens are matched and all `pathterms` are used, then the
+ `pathspec` matches
+
+ The pattern matching is done by first matching the HTTP request method to a
+ rule. ``method`` is equal to ``"*"`` by default, and will match any HTTP
+ method. It will then try to match the path to one rule. If no rule matches,
+ then a :statuscode:`404` response returned.
+
+ Once a rule is found we rewrite the request url using the ``to`` and
+ ``query`` fields. The identified token are matched to the rule and will
+ replace var. If ``'*'`` is found in the rule it will contain the remaining
+ part if it exists.
+
+ Examples:
+
+ +--------------------------------------+----------+------------------+-------+
+ | Rule | Url | Rewrite to | Tokens|
+ +======================================+==========+==================+=======+
+ | {"from": "/a", "to": "/some"} | /a | /some | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/\*", "to": "/some/\*} | /a/b/c | /some/b/c | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/b", "to": "/some"} | /a/b?k=v | /some?k=v | k=v |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/b", "to": "/some/:var"} | /a/b | /some/b?var=b | var=b |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/:foo/", | /a/b/c | /some/b/c?foo=b | foo=b |
+ | "to": "/some/:foo/"} | | | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a/:foo", "to": "/some", | /a/b | /some/?k=b&foo=b | foo=b |
+ | "query": { "k": ":foo" }} | | | |
+ +--------------------------------------+----------+------------------+-------+
+ | {"from": "/a", "to": "/some/:foo"} | /a?foo=b | /some/?b&foo=b | foo=b |
+ +--------------------------------------+----------+------------------+-------+
+
+ Request method, header, query parameters, request payload and response body
+ are depended on endpoint to which url will be rewritten.
+
+ :param db: Database name
+ :param ddoc: Design document name
+ :param path: URL path to rewrite