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:55 UTC
[28/50] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 360107b
Update Document API ref.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/77daf7cb
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/77daf7cb
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/77daf7cb
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 77daf7cbd76140131fbac98163c96d62ecf818ca
Parents: bdb45c0
Author: Alexander Shorin <kx...@apache.org>
Authored: Thu Aug 15 00:50:47 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Aug 21 20:29:40 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/bulk-api.rst | 2 +-
share/doc/src/api/database/common.rst | 2 +-
share/doc/src/api/ddoc/common.rst | 2 +-
share/doc/src/api/ddoc/index.rst | 2 +-
share/doc/src/api/ddoc/views.rst | 2 +-
share/doc/src/api/document/common.rst | 1241 +++++++++++++++++---------
share/doc/src/api/document/index.rst | 3 +-
share/doc/src/api/local.rst | 8 +-
share/doc/src/config/misc.rst | 14 +
share/doc/src/replication/protocol.rst | 4 +-
10 files changed, 866 insertions(+), 414 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/database/bulk-api.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/bulk-api.rst b/share/doc/src/api/database/bulk-api.rst
index ba0af48..d703ecb 100644
--- a/share/doc/src/api/database/bulk-api.rst
+++ b/share/doc/src/api/database/bulk-api.rst
@@ -139,7 +139,7 @@
The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
selected from the database. This enables you to request multiple
- documents in a single request, in place of multiple :ref:`api/doc.get`
+ documents in a single request, in place of multiple :http:get:`/{db}/{docid}`
requests.
The request body should contain a list of the keys to be returned as an
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index efc3b37..dc17465 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -274,7 +274,7 @@
:>header Content-Type: - :mimetype:`application/json`
- :mimetype:`text/plain; charset=utf-8`
:>header ETag: Quoted new document's revision
- :>header Location: Document URI
+ :>header Location: Document's URI
:>json string id: Created document ID
:>json boolean ok: Operation status
:>json string rev: Revision info
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/ddoc/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/common.rst b/share/doc/src/api/ddoc/common.rst
index eb3d740..c5ba9ce 100644
--- a/share/doc/src/api/ddoc/common.rst
+++ b/share/doc/src/api/ddoc/common.rst
@@ -74,7 +74,7 @@ The returned string will be the JSON of the design document:
A list of the revisions can be obtained by using the ``revs`` query
argument, or an extended list of revisions using the ``revs_info`` query
argument. This operates in the same way as for other documents. Fur
-further examples, see :ref:`api/doc.get`.
+further examples, see :http:get:`/{db}/{docid}`.
.. _api/ddoc.put:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/ddoc/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/index.rst b/share/doc/src/api/ddoc/index.rst
index a8049f4..12b9007 100644
--- a/share/doc/src/api/ddoc/index.rst
+++ b/share/doc/src/api/ddoc/index.rst
@@ -11,7 +11,7 @@
.. the License.
-.. _api/ddoc:
+.. _api/design-docs:
=======================
Design Document Methods
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index 59b830b..1ae0a60 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -602,7 +602,7 @@ Multi-document Fetching
By combining the ``POST`` method to a given view with the
``include_docs=true`` query argument you can obtain multiple documents
from a database. The result is more efficient than using multiple
-:ref:`api/doc.get` requests.
+:http:get:`/{db}/{docid}` requests.
For example, sending the following request for ingredients matching
“claret” and “clear apple juice”:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index ff2aa65..e9ca7dc 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -11,581 +11,1018 @@
.. the License.
-.. _api/doc.get:
+.. _api/doc:
-``GET /db/doc``
-===============
+``/db/doc``
+===========
-* **Method**: ``GET /db/doc``
-* **Request**: None
-* **Response**: Returns the JSON for the document
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+.. http:head:: /{db}/{docid}
- * **Argument**: conflicts
+ Returns the HTTP Headers containing a minimal amount of information
+ about the specified document. The method supports the same query
+ arguments as the :http:get:`/{db}/{docid}` method, but only the header
+ information (including document size, and the revision as an ETag), is
+ returned.
- * **Description**: Returns the conflict tree for the document.
- * **Optional**: yes
- * **Type**: boolean
- * **Default**: false
- * **Supported Values**:
+ The :http:header:`ETag` header shows the current revision for the requested
+ document, and the :http:header:`Content-Length` specifies the length of the
+ data, if the document were requested in full.
- * **true**: Includes the revisions
+ Adding any of the query arguments (see :http:get:`/{db}/{docid}`), then the
+ resulting HTTP Headers will correspond to what would be returned.
- * **Argument**: rev
+ :param db: Database name
+ :param docid: Document ID
+ :<header If-None-Match: Double quoted document's revision token
+ :>header Content-Length: Document size
+ :>header ETag: Double quoted document's revision token
+ :code 200: Document exists
+ :code 304: Document wasn't modified since specified revision
+ :code 401: Read privilege required
+ :code 404: Document not found
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
+ **Request**:
- * **true**: Includes the revisions
+ .. code-block:: http
- * **Argument**: revs
-
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
-
- * **Argument**: revs_info
-
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
- * **Supported Values**:
+ GET /db/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **true**: Includes the revisions
+ **Response**:
-* **Return Codes**:
+ .. code-block:: http
- * **200**:
- Document retrieved
- * **400**:
- The format of the request or revision was invalid
- * **404**:
- The specified document or revision cannot be found, or has been deleted
- * **409**:
- Conflict - a document with the specified document ID already exists
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 660
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "12-151bb8678d45aaa949ec3698ef1c7e78"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+
+.. http:get:: /{db}/{docid}
+
+ Returns document by the specified ``docid`` from the specified ``db``.
+ Unless you request a specific revision, the latest revision of the
+ document will always be returned.
+
+ :param db: Database name
+ :param docid: Document ID
+
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`multipart/mixed`
+ - :mimetype:`text/plain`
+ :<header If-None-Match: Double quoted document's revision token
+
+ :query boolean attachments: Includes attachments bodies in response.
+ Default is ``false``
+ :query boolean att_encoding_info: Includes encoding information into
+ attachment's stubs for compressed ones. Default is ``false``
+ :query array atts_since: Includes attachments only since specified revisions.
+ Doesn't includes attachments for specified revisions. *Optional*
+ :query boolean conflicts: Includes information about conflicts in document.
+ Default is ``false``
+ :query boolean deleted_conflicts: Includes information about deleted
+ conflicted revisions. Default is ``false``
+ :query boolean latest: Forces retrieving latest "leaf" revision, no matter
+ what `rev` was requested. Default is ``false``
+ :query boolean local_seq: Includes last update sequence number for the
+ document. Default is ``false``
+ :query boolean meta: Acts same as specifying all `conflicts`,
+ `deleted_conflicts` and `open_revs` query parameters. Default is ``false``
+ :query array open_revs: Retrieves documents of specified leaf revisions.
+ Additionally, it accepts value as ``all`` to return all leaf revisions.
+ *Optional*
+ :query string rev: Retrieves document of specified revision. *Optional*
+ :query boolean revs: Includes list of all known document revisions.
+ Default is ``false``
+ :query boolean revs_info: Includes detailed information for all known
+ document revisions. Default is ``false``
+
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`multipart/mixed`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's revision token. Not available when
+ retrieving conflicts-related information
+ :>header Transfer-Encoding: ``chunked``. Available if requested with
+ query parameter ``open_revs``
+
+ :>json string _id: Document ID
+ :>json string _rev: Revision MVCC token
+ :>json boolean _deleted: Deletion flag. Available if document was removed
+ :>json object _attachments: Attachment's stubs. Available if document has
+ any attachments
+ :>json array _conflicts: List of conflicted revisions. Available if requested
+ with ``conflicts=true`` query parameter
+ :>json array _deleted_conflicts: List of deleted conflicted revisions.
+ Available if requested with ``deleted_conflicts=true`` query parameter
+ :>json number _local_seq: Document's sequence number in current database.
+ Available if requested with ``local_seq=true`` query parameter
+ :>json array _revs_info: List of objects with information about local
+ revisions and their status. Available if requested with ``open_revs`` query
+ parameter
+ :>json object _revisions: List of local revision tokens without.
+ Available if requested with ``revs=true`` query parameter
+
+ :code 200: Request completed successfully
+ :code 304: Document wasn't modified since specified revision
+ :code 400: The format of the request or revision was invalid
+ :code 401: Read privilege required
+ :code 404: Document not found
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-Returns the specified ``doc`` from the specified ``db``. For example, to
-retrieve the document with the id ``FishStew`` you would send the
-following request:
+ **Response**:
-.. code-block:: http
+ .. code-block:: http
- GET http://couchdb:5984/recipes/FishStew
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 660
Content-Type: application/json
- Accept: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "1-917fa2381192822767f010b95b45325b"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-The returned JSON is the JSON of the document, including the document ID
-and revision number:
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "1-917fa2381192822767f010b95b45325b",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-.. code-block:: javascript
+.. http:put:: /{db}/{docid}
+
+ The :http:method:`PUT` method creates a new named document, or creates a new
+ revision of the existing document. Unlike the :http:post:`/{db}` method, you
+ must specify the document ID in the request URL.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<header If-Match: Document's revision. Alternative to `rev` query parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Quoted document's new revision
+ :>header Location: Document URI
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 201: Document created and stored on disk
+ :code 202: Document data accepted, but not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database or document ID doesn't exists
+ :code 409: Document with the specified ID already exists or specified
+ revision is not latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 196
+ Content-Type: application/json
+ Host: localhost:5984
{
- "_id" : "FishStew",
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "title" : "Irish Fish Stew"
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
}
+ **Response**:
-Unless you request a specific revision, the latest revision of the
-document will always be returned.
+ .. code-block:: http
-Attachments
------------
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 20:31:39 GMT
+ ETag: "1-917fa2381192822767f010b95b45325b"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-If the document includes attachments, then the returned structure will
-contain a summary of the attachments associated with the document, but
-not the attachment data itself.
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "1-917fa2381192822767f010b95b45325b"
+ }
-The JSON for the returned document will include the ``_attachments``
-field, with one or more attachment definitions. For example:
-.. code-block:: javascript
+.. http:delete:: /{db}/{docid}
+
+ Deletes the specified document from the database. You must supply the
+ current (latest) revision, either by using the ``rev`` parameter to
+ specify the revision.
+
+ .. note::
+ Note that deletion of a record increments the revision number.
+ The use of a revision for deletion of the record allows replication of
+ the database to correctly track the deletion in synchronized copies.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header If-Match: Document's revision. Alternative to `rev` query parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string rev: Actual document's revision
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's new revision
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 200: Document successfully removed
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Write privileges required
+ :code 404: Specified database or document ID doesn't exists
+ :code 409: Specified revision is not latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- "_attachments" : {
- "styling.css" : {
- "stub" : true,
- "content-type" : "text/css",
- "length" : 783426,
- },
- },
- }
+ Alternatively, instead of ``rev`` query parameter you may use
+ :http:header:`If-Match` header:
-The format of the returned JSON is shown in the table below:
+ .. code-block:: http
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_attachments** (optional): Document Attachment
+ DELETE /recipes/FishStew HTTP/1.1
+ Accept: application/json
+ If-Match: 1-9c65296036141e575d32ba9c034dd3ee
+ Host: localhost:5984
- * **filename**: Attachment information
+ **Response**:
- * **content_type**: MIME Content type string
- * **length**: Length (bytes) of the attachment data
- * **revpos**: Revision where this attachment exists
- * **stub**: Indicates whether the attachment is a stub
+ .. code-block:: http
-Getting a List of Revisions
----------------------------
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 71
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:23:13 GMT
+ ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-You can obtain a list of the revisions for a given document by adding
-the ``revs=true`` parameter to the request URL. For example:
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
+ }
-.. code-block:: http
- GET http://couchdb:5984/recipes/FishStew?revs=true
+.. http:copy:: /{db}/{docid}
+
+ The :http:method:`COPY` (which is non-standard HTTP) copies an existing
+ document to a new or existing document.
+
+ The source document is specified on the request line, with the
+ :http:header:`Destination` header of the request specifying the target
+ document.
+
+ :param db: Database name
+ :param docid: Document ID
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Destination: Destination document
+ :<header If-Match: Source document's revision. Alternative to `rev` query
+ parameter
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*
+ :query string rev: Revision to copy from. *Optional*
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Double quoted document's new revision
+ :>header Location: Document's URI
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision MVCC token
+ :code 201: Document successfully created
+ :code 202: Request was accepted, but changes are not yet stored on disk
+ :code 400: Invalid request body or parameters
+ :code 401: Read or write privileges required
+ :code 404: Specified database, document ID or his revision doesn't exists
+ :code 409: Document with the specified ID already exists or specified
+ revision is not latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
+ Destination: SpaghettiWithMeatballs_Italian
+ Host: localhost:5984
-The returned JSON structure includes the original document, including a
-``_revisions`` structure that includes the revision information:
+ **Response**:
-.. code-block:: javascript
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 93
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 14:21:00 GMT
+ ETag: "1-e86fdf912560c2321a5fcefc6264e6d9"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
{
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "_id" : "FishStew",
- "title" : "Irish Fish Stew",
- "_revisions" : {
- "ids" : [
- "a1a9b39ee3cc39181b796a69cb48521c",
- "7c4740b4dcf26683e941d6641c00c39d",
- "9c65296036141e575d32ba9c034dd3ee"
- ],
- "start" : 3
- },
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ "id": "SpaghettiWithMeatballs_Italian",
+ "ok": true,
+ "rev": "1-e86fdf912560c2321a5fcefc6264e6d9"
}
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_revisions**: CouchDB Document Revisions
- * **ids** [array]: Array of valid revision IDs, in reverse order
- (latest first)
- * **start**: Prefix number for the latest revision
+.. _api/doc/attachments:
-Obtaining an Extended Revision History
---------------------------------------
+Attachments
+-----------
-You can get additional information about the revisions for a given
-document by supplying the ``revs_info`` argument to the query:
+If the document includes attachments, then the returned structure will
+contain a summary of the attachments associated with the document, but
+not the attachment data itself.
+
+The JSON for the returned document will include the ``_attachments``
+field, with one or more attachment definitions.
+
+The ``_attachments`` object keys are attachments names while values are
+information objects with next structure:
+
+- **content_type** (*string*): Attachment MIME type
+- **data** (*string*): Base64-encoded content. Available if attachment content
+ requested by using ``attachments=true`` or ``atts_since`` query parameters
+- **digest** (*string*): Content hash digest.
+ It starts with prefix which announce hash type (``md5-``) and continues with
+ Base64-encoded hash digest
+- **encoded_length** (*number*): Compressed attachment size in bytes
+ Available when query parameter ``att_encoding_info=true`` was specified and
+ ``content_type`` is in :ref:`list of compressiable types
+ <config/attachments/compressible_types>`
+- **encoding** (*string*): Compression codec. Available when query parameter
+ ``att_encoding_info=true`` was specified
+- **length** (*number*): Real attachment size in bytes. Not available if attachment
+ content requested
+- **revpos** (*number*): Revision *number* when attachment was added
+- **stub** (*boolean*): Has ``true`` value if object contains stub info and no
+ content. Otherwise omitted in response
+
+
+Basic Attachments Info
+^^^^^^^^^^^^^^^^^^^^^^
+
+**Request**:
.. code-block:: http
- GET http://couchdb:5984/recipes/FishStew?revs_info=true
- Accept: application/json
+ GET /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-This returns extended revision information, including the availability
-and status of each revision:
+**Response**:
-.. code-block:: javascript
+.. code-block:: http
- {
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "_id" : "FishStew",
- "_revs_info" : [
- {
- "status" : "available",
- "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 660
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
},
- {
- "status" : "available",
- "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "length": 85,
+ "revpos": 5,
+ "stub": true
},
- {
- "status" : "available",
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ "photo.jpg": {
+ "content_type": "image/jpeg",
+ "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
+ "length": 165504,
+ "revpos": 2,
+ "stub": true
}
- ],
- "title" : "Irish Fish Stew",
- "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
- }
+ },
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_revs_info** [array]: CouchDB Document Extended Revision Info
- * **rev**: Full revision string
- * **status**: Status of the revision
+Retrieving Attachments Content
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Obtaining a Specific Revision
------------------------------
+It's possible to retrieve document with all attached files content by using
+``attachements=true`` query parameter:
-To get a specific revision, use the ``rev`` argument to the request, and
-specify the full revision number:
+**Request**:
.. code-block:: http
- GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
- Accept: application/json
-
-The specified revision of the document will be returned, including a
-``_rev`` field specifying the revision that was requested:
+ GET /db/pixel?attachments=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-.. code-block:: javascript
+**Response**:
- {
- "_id" : "FishStew",
- "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
- "servings" : 4,
- "subtitle" : "Delicious with a green salad",
- "title" : "Fish Stew"
- }
+.. code-block:: http
-.. _api/doc.head:
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 553
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:32:40 GMT
+ ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "pixel.gif": {
+ "content_type": "image/gif",
+ "data": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
+ "digest": "md5-2JdGiI2i2VELZKnwMers1Q==",
+ "revpos": 2
+ },
+ "pixel.png": {
+ "content_type": "image/png",
+ "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAAXNSR0IArs4c6QAAAANQTFRFAAAAp3o92gAAAAF0Uk5TAEDm2GYAAAABYktHRACIBR1IAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3QgOCx8VHgmcNwAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=",
+ "digest": "md5-Dgf5zxgGuchWrve73evvGQ==",
+ "revpos": 3
+ }
+ },
+ "_id": "pixel",
+ "_rev": "4-f1bcae4bf7bbb92310079e632abfe3f4"
+ }
-``HEAD /db/doc``
-================
+Or retrieve attached files content since specific revision using ``atts_since``
+query parameter:
-* **Method**: ``HEAD /db/doc``
-* **Request**: None
-* **Response**: None
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+**Request**:
- * **Argument**: rev
+.. code-block:: http
- * **Description**: Specify the revision to return
- * **Optional**: yes
- * **Type**: string
+ GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22] HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **Argument**: revs
+**Response**:
- * **Description**: Return a list of the revisions for the document
- * **Optional**: yes
- * **Type**: boolean
+.. code-block:: http
- * **Argument**: revs_info
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 760
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
+ },
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "data": "MS4gQ29vayBzcGFnaGV0dGkKMi4gQ29vayBtZWV0YmFsbHMKMy4gTWl4IHRoZW0KNC4gQWRkIHRvbWF0byBzYXVjZQo1LiAuLi4KNi4gUFJPRklUIQ==",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "revpos": 5
+ },
+ "photo.jpg": {
+ "content_type": "image/jpeg",
+ "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
+ "length": 165504,
+ "revpos": 2,
+ "stub": true
+ }
+ },
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
- * **Description**: Return a list of detailed revision information for the
- document
- * **Optional**: yes
- * **Type**: boolean
-* **Return Codes**:
+Retrieving Attachments Encoding Info
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- * **404**:
- The specified document or revision cannot be found, or has been deleted
+By using ``att_encoding_info=true`` query parameter you may retrieve information
+about compressed attachments size and used codec.
-Returns the HTTP Headers containing a minimal amount of information
-about the specified document. The method supports the same query
-arguments as the ``GET`` method, but only the header information
-(including document size, and the revision as an ETag), is returned. For
-example, a simple ``HEAD`` request:
+**Request**:
.. code-block:: http
- HEAD http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
+ GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+**Response**:
-Returns the following HTTP Headers:
+.. code-block:: http
-.. code-block:: javascript
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 736
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 21:35:37 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "encoded_length": 693,
+ "encoding": "gzip",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
+ },
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "encoded_length": 100,
+ "encoding": "gzip",
+ "length": 85,
+ "revpos": 5,
+ "stub": true
+ },
+ "photo.jpg": {
+ "content_type": "image/jpeg",
+ "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
+ "length": 165504,
+ "revpos": 2,
+ "stub": true
+ }
+ },
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
- HTTP/1.1 200 OK
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
- Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
- Date: Fri, 05 Nov 2010 14:54:43 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 136
- Cache-Control: must-revalidate
-The ``Etag`` header shows the current revision for the requested
-document, and the ``Content-Length`` specifies the length of the data,
-if the document were requested in full.
+Getting a List of Revisions
+---------------------------
+
+You can obtain a list of the revisions for a given document by adding
+the ``revs=true`` parameter to the request URL:
-Adding any of the query arguments (as supported by ```GET```_ method),
-then the resulting HTTP Headers will correspond to what would be
-returned. Note that the current revision is not returned when the
-``refs_info`` argument is used. For example:
+**Request**:
.. code-block:: http
- HTTP/1.1 200 OK
- Server: CouchDB/1.0.1 (Erlang OTP/R13B)
- Date: Fri, 05 Nov 2010 14:57:16 GMT
- Content-Type: text/plain;charset=utf-8
- Content-Length: 609
- Cache-Control: must-revalidate
-
-.. _api/doc.put:
+ GET /recipes/SpaghettiWithMeatballs?revs=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-``PUT /db/doc``
-===============
+**Response**:
-* **Method**: ``PUT /db/doc``
-* **Request**: JSON of the new document, or updated version of the existed
- document
-* **Response**: JSON of the document ID and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+.. code-block:: http
- * **Argument**: batch
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 584
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:38:26 GMT
+ ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "_revisions": {
+ "ids": [
+ "6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "77fba3a059497f51ec99b9b478b569d2",
+ "136813b440a00a24834f5cb1ddf5b1f1",
+ "fd96acb3256302bf0dd2f32713161f2a",
+ "874985bc28906155ba0e2e0538f67b05",
+ "0de77a37463bf391d14283e626831f2e",
+ "d795d1b924777732fdea76538c558b62",
+ "917fa2381192822767f010b95b45325b"
+ ],
+ "start": 8
+ },
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
- * **Description**: Allow document store request to be batched with others
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**:
- * **ok**: Enable
+The returned JSON structure includes the original document, including a
+``_revisions`` structure that includes the revision information in next form:
-* **HTTP Headers**
+- **ids** (*array*): Array of valid revision IDs, in reverse order
+ (latest first)
+- **start** (*number*): Prefix number for the latest revision
- * **Header**: ``If-Match``
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
+Obtaining an Extended Revision History
+--------------------------------------
-* **Return Codes**:
+You can get additional information about the revisions for a given
+document by supplying the ``revs_info`` argument to the query:
- * **201**:
- Document has been created successfully
- * **202**:
- Document accepted for writing (batch mode)
+**Request**:
+.. code-block:: http
-The ``PUT`` method creates a new named document, or creates a new
-revision of the existing document. Unlike the ``POST`` method, you
-must specify the document ID in the request URL.
+ GET /recipes/SpaghettiWithMeatballs?revs_info=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-For example, to create the document ``FishStew``, you would send the
-following request:
+**Response**:
.. code-block:: http
- PUT http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The return type is JSON of the status, document ID,and revision number:
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 802
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:40:55 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "_revs_info": [
+ {
+ "rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
+ "status": "available"
+ },
+ {
+ "rev": "7-77fba3a059497f51ec99b9b478b569d2",
+ "status": "deleted"
+ },
+ {
+ "rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
+ "status": "available"
+ },
+ {
+ "rev": "5-fd96acb3256302bf0dd2f32713161f2a",
+ "status": "missing"
+ },
+ {
+ "rev": "4-874985bc28906155ba0e2e0538f67b05",
+ "status": "missing"
+ },
+ {
+ "rev": "3-0de77a37463bf391d14283e626831f2e",
+ "status": "missing"
+ },
+ {
+ "rev": "2-d795d1b924777732fdea76538c558b62",
+ "status": "missing"
+ },
+ {
+ "rev": "1-917fa2381192822767f010b95b45325b",
+ "status": "missing"
+ }
+ ],
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-.. code-block:: javascript
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
+The returned document contains ``_rev_info`` field with extended revision
+information, including the availability and status of each revision. This array
+field contains objects with following structure:
-Updating an Existing Document
------------------------------
+- **rev** (*string*): Full revision string
+- **status** (*string*): Status of the revision.
+ Maybe one of:
-To update an existing document you must specify the current revision
-number within the ``_rev`` parameter. For example:
+ - ``available``: Revision is available for retrieving with `rev` query
+ parameter
+ - ``missing``: Revision is not available
+ - ``deleted``: Revision belongs to deleted document
-.. code-block:: http
- PUT http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
+Obtaining a Specific Revision
+-----------------------------
- {
- "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
- "servings" : 4,
- "subtitle" : "Delicious with fresh salad",
- "title" : "Fish Stew"
- }
+To get a specific revision, use the ``rev`` argument to the request, and
+specify the full revision number. The specified revision of the document will
+be returned, including a ``_rev`` field specifying the revision that was
+requested.
-Alternatively, you can supply the current revision number in the
-``If-Match`` HTTP header of the request. For example:
+**Request**:
.. code-block:: http
- PUT http://couchdb:5984/recipes/FishStew
- If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
- Content-Type: application/json
+ GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh salad",
- "title" : "Fish Stew"
- }
+**Response**:
-The JSON returned will include the updated revision number:
+.. code-block:: http
-.. code-block:: javascript
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 271
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 11:40:55 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
- {
- "id" : "FishStew99",
- "ok" : true,
- "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
- }
+ {
+ "_id": "SpaghettiWithMeatballs",
+ "_rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
-For information on batched writes, which can provide improved
-performance, see :ref:`api/doc/batch-writes`.
-.. _api/doc.delete:
+Retrieving Deleted Documents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``DELETE /db/doc``
-==================
+CouchDB doesn't actually deletes documents via :http:delete:`/{db}/{docid}`.
+Instead of this, it leaves tombstone with very basic information about document.
+If you just :http:get:`/{db}/{docid}` CouchDB returns :http:statuscode:`404`
+response:
-* **Method**: ``DELETE /db/doc``
-* **Request**: None
-* **Response**: JSON of the deleted revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
+**Request**:
- * **Argument**: rev
+.. code-block:: http
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
- * **Type**: string
+ GET /recipes/FishStew HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-* **HTTP Headers**
+**Response**:
- * **Header**: ``If-Match``
+.. code-block:: http
- * **Description**: Current revision of the document for validation
- * **Optional**: yes
+ HTTP/1.1 404 Object Not Found
+ Cache-Control: must-revalidate
+ Content-Length: 41
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:23:27 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-* **Return Codes**:
+ {
+ "error": "not_found",
+ "reason": "deleted"
+ }
- * **409**:
- Revision is missing, invalid or not the latest
+However, you may retrieve document's tombstone by using ``rev`` query parameter
+with :http:get:`/{db}/{docid}` request:
-Deletes the specified document from the database. You must supply the
-current (latest) revision, either by using the ``rev`` parameter to
-specify the revision:
+**Request**:
.. code-block:: http
- DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
- Content-Type: application/json
+ GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
-Alternatively, you can use ETags with the ``If-Match`` field:
+**Response**:
.. code-block:: http
- DELETE http://couchdb:5984/recipes/FishStew
- If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
- Content-Type: application/json
-
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Length: 79
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 12:30:22 GMT
+ ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-The returned JSON contains the document ID, revision and status:
+ {
+ "_deleted": true,
+ "_id": "FishStew",
+ "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
+ }
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "4-2719fd41187c60762ff584761b714cfb"
- }
-.. note:: Note that deletion of a record increments the revision number. The
- use of a revision for deletion of the record allows replication of
- the database to correctly track the deletion in synchronized copies.
-
-.. _api/doc.copy:
-
-``COPY /db/doc``
-================
-
-* **Method**: ``COPY /db/doc``
-* **Request**: None
-* **Response**: JSON of the new document and revision
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: rev
+Updating an Existing Document
+-----------------------------
- * **Description**: Revision to copy from
- * **Optional**: yes
- * **Type**: string
+To update an existing document you must specify the current revision
+number within the ``_rev`` parameter.
-* **HTTP Headers**
+**Request**:
- * **Header**: ``Destination``
+.. code-block:: http
- * **Description**: Destination document (and optional revision)
- * **Optional**: no
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 258
+ Content-Type: application/json
+ Host: localhost:5984
+
+ {
+ "_rev": "1-917fa2381192822767f010b95b45325b",
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs",
+ "serving": "hot"
+ }
-* **Return Codes**:
+Alternatively, you can supply the current revision number in the
+``If-Match`` HTTP header of the request:
- * **201**:
- Document has been copied and created successfully
- * **409**:
- Revision is missing, invalid or not the latest
+.. code-block:: http
-The ``COPY`` command (which is non-standard HTTP) copies an existing
-document to a new or existing document.
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 258
+ Content-Type: application/json
+ If-Match: 1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
-The source document is specified on the request line, with the
-``Destination`` HTTP Header of the request specifying the target
-document.
+ {
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs",
+ "serving": "hot"
+ }
-Copying a Document
-------------------
-You can copy the latest version of a document to a new document by
-specifying the current document and target document:
+**Response**:
.. code-block:: http
- COPY http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Destination: IrishFishStew
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 85
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 20:33:56 GMT
+ ETag: "2-790895a73b63fb91dd863388398483dd"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
-The above request copies the document ``FishStew`` to the new document
-``IrishFishStew``. The response is the ID and revision of the new
-document.
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "2-790895a73b63fb91dd863388398483dd"
+ }
-.. code-block:: javascript
-
- {
- "id" : "IrishFishStew",
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
Copying from a Specific Revision
--------------------------------
To copy *from* a specific version, use the ``rev`` argument to the query
-string:
+string or :http:header:`If-Match`:
+
+**Request**:
.. code-block:: http
- COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
- Content-Type: application/json
- Destination: IrishFishStew
+ COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Destination: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
+ If-Match: 1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 93
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 14:21:00 GMT
+ ETag: "1-917fa2381192822767f010b95b45325b"
+ Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "SpaghettiWithMeatballs_Original",
+ "ok": true,
+ "rev": "1-917fa2381192822767f010b95b45325b"
+ }
-The new document will be created using the information in the specified
-revision of the source document.
Copying to an Existing Document
-------------------------------
To copy to an existing document, you must specify the current revision
-string for the target document, using the ``rev`` parameter to the
-``Destination`` HTTP Header string. For example:
+string for the target document by appending the ``rev`` parameter to the
+:http:header:`Destination` header string.
-.. code-block:: http
+**Request**:
- COPY http://couchdb:5984/recipes/FishStew
- Content-Type: application/json
- Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee
+.. code-block:: http
-The return value will be the new revision of the copied document:
+ COPY /recipes/SpaghettiWithMeatballs?rev=8-6f5ad8db0f34af24a6e0984cd1a6cfb9 HTTP/1.1
+ Accept: application/json
+ Destination: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original?rev=1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
-.. code-block:: javascript
+**Response**:
- {
- "id" : "IrishFishStew",
- "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
- }
+.. code-block:: http
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 93
+ Content-Type: application/json
+ Date: Wed, 14 Aug 2013 14:21:00 GMT
+ ETag: "2-62e778c9ec09214dd685a981dcc24074""
+ Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "SpaghettiWithMeatballs_Original",
+ "ok": true,
+ "rev": "2-62e778c9ec09214dd685a981dcc24074"
+ }
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/document/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/index.rst b/share/doc/src/api/document/index.rst
index d471b90..778e807 100644
--- a/share/doc/src/api/document/index.rst
+++ b/share/doc/src/api/document/index.rst
@@ -10,7 +10,8 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. _api/doc:
+
+.. _api/document:
================
Document Methods
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
index b08de5e..83a64cf 100644
--- a/share/doc/src/api/local.rst
+++ b/share/doc/src/api/local.rst
@@ -59,22 +59,22 @@ A list of the available methods and URL paths are provided below:
Gets the specified local document. The semantics are identical to
accessing a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.get`.
+ document is not replicated. See :http:get:`/{db}/{docid}`.
.. http:put:: /{db}/_local/{id}
Stores the specified local document. The semantics are identical to
storing a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.put`.
+ document is not replicated. See :http:put:`/{db}/{docid}`.
.. http:delete:: /{db}/_local/{id}
Deletes the specified local document. The semantics are identical to
deleting a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.delete`.
+ document is not replicated. See :http:delete:`/{db}/{docid}`.
.. http:copy:: /{db}/_local/{id}
Copies the specified local document. The semantics are identical to
copying a standard document in the specified database, except that the
- document is not replicated. See :ref:`api/doc.copy`.
+ document is not replicated. See :http:copy:`/{db}/{docid}`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/config/misc.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/config/misc.rst b/share/doc/src/config/misc.rst
index b373496..ffd9041 100644
--- a/share/doc/src/config/misc.rst
+++ b/share/doc/src/config/misc.rst
@@ -171,6 +171,20 @@ Available algorithms:
]
}
+.. note:: **Impact of UUID choices:**
+ The choice of UUID has a significant impact on the layout of the B-tree,
+ prior to compaction.
+
+ For example, a sequential UUID algorithm during uploading thousands of
+ documents, will avoid the need to rewrite many intermediate B-tree nodes.
+ A random UUID algorithm may require rewriting intermediate nodes on a regular
+ basis, with a corresponding decrease of throughput, and significant wasted
+ space due to the append-only B-tree design.
+
+ It is generally recommended to set your own UUIDs, or use the sequential
+ algorithm unless you have a specific need and take into account the likely
+ need for compaction to re-balance the B-tree and reclaim wasted space.
+
.. _config/uuids/utc_id_suffix:
http://git-wip-us.apache.org/repos/asf/couchdb/blob/77daf7cb/share/doc/src/replication/protocol.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/replication/protocol.rst b/share/doc/src/replication/protocol.rst
index 0aac7a7..3aae5c1 100644
--- a/share/doc/src/replication/protocol.rst
+++ b/share/doc/src/replication/protocol.rst
@@ -164,7 +164,7 @@ Push Only
- :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
+- :http:put:`/{db}/{docid}`?new_edits=false -- Upload a single Document with
attachments to the Target
Pull Only
@@ -179,7 +179,7 @@ Pull Only
- ``limit=limit``
- ``heartbeat=heartbeat``
-- :ref:`api/doc.get` -- Retrieve a single Document from Source with attachments.
+- :http:get:`/{db}/{docid}` -- Retrieve a single Document from Source with attachments.
The request uses next query parameters:
- ``open_revs=revid`` - where ``revid`` is the actual Document Revision at the