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 2013/08/21 18:37:57 UTC
[30/50] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 360107b
Update Database misc API reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/c6af82e0
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/c6af82e0
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/c6af82e0
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: c6af82e00c1b061b1b2f472f28afeeba88ba006d
Parents: edacbca
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Aug 12 22:52:03 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Aug 21 20:29:40 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/misc.rst | 330 ++++++++++++++++++++--------
share/doc/src/replication/protocol.rst | 5 +-
2 files changed, 244 insertions(+), 91 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c6af82e0/share/doc/src/api/database/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/misc.rst b/share/doc/src/api/database/misc.rst
index 6355d2e..b0c3706 100644
--- a/share/doc/src/api/database/misc.rst
+++ b/share/doc/src/api/database/misc.rst
@@ -12,66 +12,88 @@
.. _api/db/purge:
-.. _api/db/purge.post:
-``POST /db/_purge``
-===================
+``/db/_purge``
+==============
+
+.. http:post:: /{db}/_purge
+
+ A database purge permanently removes the references to deleted documents
+ from the database. Deleting a document within CouchDB does not actually
+ remove the document from the database, instead, the document is marked as
+ a deleted (and a new revision is created). This is to ensure that
+ deleted documents are 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.
+
+ 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.
-* **Method**: ``POST /db/_purge``
-* **Request**: JSON of the document IDs/revisions to be purged
-* **Response**: JSON structure with purged documents and purge sequence
-* **Admin Privileges Required**: no
+ .. note::
-A database purge permanently removes the references to deleted documents
-from the database. Deleting a document within CouchDB does not actually
-remove the document from the database, instead, the document is marked as
-a deleted (and a new revision is created). This is to ensure that
-deleted documents are 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.
+ 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 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.
+ The format of the request must include the document ID and one or more
+ revisions that must be purged.
-.. note::
+ The response will contain the purge sequence number, and a list of the
+ document IDs and revisions successfully purged.
- 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`).
+ :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 :http:header:`Content-Type` value
-To perform a purge operation you must send a request including the JSON
-of the document IDs that you want to purge. For example:
+ **Request**:
-.. code-block:: http
+ .. code-block:: http
- POST http://couchdb:5984/recipes/_purge
+ POST /db/_purge HTTP/1.1
+ Accept: application/json
+ Content-Length: 76
Content-Type: application/json
+ Host: localhost:5984
{
- "FishStew" : [
- "17-b3eb5ac6fbaef4428d712e66483dcb79"
- ]
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
+ "3-0e871ef78849b0c206091f1a7af6ec41"
+ ]
}
-The format of the request must include the document ID and one or more
-revisions that must be purged.
+ **Response**:
-The response will contain the purge sequence number, and a list of the
-document IDs and revisions successfully purged.
+ .. code-block:: http
-.. code-block:: javascript
+ 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/1.4.0 (Erlang OTP/R16B)
{
- "purged" : {
- "FishStew" : [
- "17-b3eb5ac6fbaef4428d712e66483dcb79"
- ]
- },
- "purge_seq" : 11
+ "purge_seq":3,
+ "purged":{
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
+ ]
+ }
}
+
Updating Indexes
----------------
@@ -92,88 +114,218 @@ 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:
-.. _api/db/missing_revs.post:
-``POST /db/_missing_revs``
-==========================
+``/db/_missing_revs``
+=====================
+
+.. http:post:: /{db}/_missing_revs
+
+ 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/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "missed_revs":{
+ "c6114c65e295552ab1019e2b046b10e": [
+ "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
+ ]
+ }
+ }
-* **Method**: ``POST /db/_missing_revs``
-* **Request**: JSON list of document revisions
-* **Response**: JSON of missing revisions
-* **Admin Privileges Required**: no
.. _api/db/revs_diff:
-.. _api/db/revs_diff.post:
-``POST /db/_revs_diff``
-=======================
+``/db/_revs_diff``
+==================
-* **Method**: ``POST /db/_revs_diff``
-* **Request**: JSON list of document revisions
-* **Response**: JSON list of differences from supplied document/revision list
-* **Admin Privileges Required**: no
+.. http:post:: /{db}/_revs_diff
+ 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.
-.. _api/db/revs_limit:
-.. _api/db/revs_limit.get:
+ Both the request and response bodies are JSON objects whose keys are document
+ IDs; but the values are structured differently:
-``GET /db/_revs_limit``
-=======================
+ - In the request, a value is an array of revision IDs for that document.
-* **Method**: ``GET /db/_revs_limit``
-* **Request**: None
-* **Response**: The current revision limit setting
-* **Admin Privileges Required**: no
+ - 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 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
-Gets the current ``revs_limit`` (revision limit) setting.
+ **Request**:
-For example to get the current limit:
+ .. code-block:: http
-.. 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"
+ ]
+ }
- GET http://couchdb:5984/recipes/_revs_limit
+ **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/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "190f721ca3411be7aa9477db5f948bbb": {
+ "missing": [
+ "3-bb72a7682290f94a985f7afac8b27137"
+ ]
+ }
+ }
+
+
+.. _api/db/revs_limit:
+
+``/db/_revs_limit``
+===================
+
+.. http:get:: /{db}/_revs_limit
+
+ Gets the current ``revs_limit`` (revision limit) setting.
+
+ :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
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /db/_revs_limit HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-The returned information is the current setting as a numerical scalar:
+ **Response**:
-.. code-block:: javascript
+ .. code-block:: http
+
+ 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/1.4.0 (Erlang OTP/R16B)
1000
-.. _api/db/revs_limit.put:
-``PUT /db/_revs_limit``
-=======================
+.. http:put:: /{db}/_revs_limit
-* **Method**: ``PUT /db/_revs_limit``
-* **Request**: A scalar integer of the revision limit setting
-* **Response**: Confirmation of setting of the revision limit
-* **Admin Privileges Required**: no
+ 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 by using ``PUT`` 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
-For example to set the revs limit to 100 for the ``recipes`` database:
+ **Request**:
-.. code-block:: http
+ .. code-block:: http
- PUT http://couchdb:5984/recipes/_revs_limit
+ PUT /db/_revs_limit HTTP/1.1
+ Accept: application/json
+ Content-Length: 5
Content-Type: application/json
+ Host: localhost:5984
- 100
+ 1000
-If the setting was successful, a JSON status object will be returned:
+ **Response**:
-.. code-block:: javascript
+ .. 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/1.4.0 (Erlang OTP/R16B)
{
- "ok" : true
+ "ok": true
}
-
-.. _JSON object: #table-couchdb-api-db_db-json-changes
-
http://git-wip-us.apache.org/repos/asf/couchdb/blob/c6af82e0/share/doc/src/replication/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/protocol.rst b/share/doc/src/replication/protocol.rst
index f81dcdd..0aac7a7 100644
--- a/share/doc/src/replication/protocol.rst
+++ b/share/doc/src/replication/protocol.rst
@@ -152,7 +152,8 @@ API Reference
-------------
- :http:head:`/{db}` -- Check Database existence
-- :ref:`api/db/ensure_full_commit` -- Ensure that all changes are stored on disk
+- :http:post:`/{db}/_ensure_full_commit` -- Ensure that all changes are stored
+ on disk
- :http:get:`/{db}/_local/{id}` -- Read the last Checkpoint
- :http:put:`/{db}/_local/{id}` -- Save a new Checkpoint
@@ -160,7 +161,7 @@ Push Only
~~~~~~~~~
- :http:put:`/{db}` -- Create Target if it not exists and option was provided
-- :ref:`api/db/revs_diff.post` -- Locate Revisions that are not known to the
+- :http:post:`/{db}/_revs_diff` -- Locate Revisions that are not known to the
Target
- :http:post:`/{db}/_bulk_docs` -- Upload Revisions to the Target
- :ref:`api/doc.put`?new_edits=false -- Upload a single Document with