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:51 UTC
[18/26] documentation commit: updated refs/heads/master to 5a81ace
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/src/api/document/common.rst b/src/api/document/common.rst
index 5512d88..021c557 100644
--- a/src/api/document/common.rst
+++ b/src/api/document/common.rst
@@ -10,390 +10,392 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/doc:
+===========
``/db/doc``
===========
.. http:head:: /{db}/{docid}
- :synopsis: Returns bare information in the HTTP Headers for the document
-
- Returns the HTTP Headers containing a minimal amount of information
- about the specified document. The method supports the same query
- arguments as the :get:`/{db}/{docid}` method, but only the header
- information (including document size, and the revision as an ETag), is
- returned.
+ :synopsis: Returns bare information in the HTTP Headers for the document
- The :header:`ETag` header shows the current revision for the requested
- document, and the :header:`Content-Length` specifies the length of the
- data, if the document were requested in full.
+ Returns the HTTP Headers containing a minimal amount of information about
+ the specified document. The method supports the same query arguments as the
+ :get:`/{db}/{docid}` method, but only the header information (including
+ document size, and the revision as an ETag), is returned.
- Adding any of the query arguments (see :get:`/{db}/{docid}`), then the
- resulting HTTP Headers will correspond to what would be returned.
+ The :header:`ETag` header shows the current revision for the requested
+ document, and the :header:`Content-Length` specifies the length of the
+ data, if the document were requested in full.
- :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
+ Adding any of the query arguments (see :get:`/{db}/{docid}`), then the
+ resulting HTTP Headers will correspond to what would be returned.
- **Request**:
+ :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
- .. code-block:: http
+ **Request**:
- HEAD /db/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ .. code-block:: http
- **Response**:
+ HEAD /db/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- .. code-block:: http
+ **Response**:
- 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 (Erlang/OTP)
+ .. code-block:: http
+ 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 (Erlang/OTP)
.. http:get:: /{db}/{docid}
- :synopsis: Returns the document
-
- 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 in attachment
- stubs if the particular attachment is compressed. 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
-
- **Response**:
-
- .. code-block:: http
-
- 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: "1-917fa2381192822767f010b95b45325b"
- Server: CouchDB (Erlang/OTP)
-
- {
- "_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"
- }
+ :synopsis: Returns the document
+
+ 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 in
+ attachment stubs if the particular attachment is compressed. 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
+
+ **Response**:
+
+ .. code-block:: http
+
+ 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: "1-917fa2381192822767f010b95b45325b"
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "_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"
+ }
.. http:put:: /{db}/{docid}
- :synopsis: Creates a new document or new version of an existing document
-
- The :method:`PUT` method creates a new named document, or creates a new
- revision of the existing document. Unlike the :post:`/{db}`, 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
- :config:option:`commit policy <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: 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
-
- {
- "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
- "ingredients": [
- "spaghetti",
- "tomato sauce",
- "meatballs"
- ],
- "name": "Spaghetti with meatballs"
- }
-
- **Response**:
-
- .. code-block:: http
-
- 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 (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs",
- "ok": true,
- "rev": "1-917fa2381192822767f010b95b45325b"
- }
+ :synopsis: Creates a new document or new version of an existing document
+
+ The :method:`PUT` method creates a new named document, or creates a new
+ revision of the existing document. Unlike the :post:`/{db}`, 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
+ :config:option:`commit policy <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: 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
+
+ {
+ "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
+ "ingredients": [
+ "spaghetti",
+ "tomato sauce",
+ "meatballs"
+ ],
+ "name": "Spaghetti with meatballs"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ 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 (Erlang/OTP)
+
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "1-917fa2381192822767f010b95b45325b"
+ }
.. http:delete:: /{db}/{docid}
- :synopsis: Deletes the document
-
- Marks the specified document as deleted by adding a field ``_deleted`` with
- the value ``true``. Documents with this field will not be returned within
- requests anymore, but stay in the database. You must supply the current
- (latest) revision, either by using the ``rev`` parameter or by using the
- :header:`If-Match` header to specify the revision.
-
- .. note::
- CouchDB doesn't completely delete the specified document. Instead, it leaves
- a tombstone with very basic information about the document. The tombstone
- is required so that the delete action can be replicated across databases.
-
- .. seealso::
- :ref:`Retrieving Deleted Documents <api/doc/retrieving-deleted-documents>`
-
- :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
- :config:option:`commit policy <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: 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 the latest for target document
-
- **Request**:
-
- .. code-block:: http
-
- DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1
- Accept: application/json
- Host: localhost:5984
-
- Alternatively, instead of ``rev`` query parameter you may use
- :header:`If-Match` header:
-
- .. code-block:: http
-
- DELETE /recipes/FishStew HTTP/1.1
- Accept: application/json
- If-Match: 1-9c65296036141e575d32ba9c034dd3ee
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- 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 (Erlang/OTP)
-
- {
- "id": "FishStew",
- "ok": true,
- "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
- }
-
+ :synopsis: Deletes the document
+
+ Marks the specified document as deleted by adding a field ``_deleted`` with
+ the value ``true``. Documents with this field will not be returned within
+ requests anymore, but stay in the database. You must supply the current
+ (latest) revision, either by using the ``rev`` parameter or by using the
+ :header:`If-Match` header to specify the revision.
+
+ .. note::
+ CouchDB doesn't completely delete the specified document. Instead, it
+ leaves a tombstone with very basic information about the document. The
+ tombstone is required so that the delete action can be replicated
+ across databases.
+
+ .. seealso::
+ :ref:`Retrieving Deleted Documents <api/doc/retrieving-deleted-documents>`
+
+ :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
+ :config:option:`commit policy <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: 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 the latest for target document
+
+ **Request**:
+
+ .. code-block:: http
+
+ DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ Alternatively, instead of ``rev`` query parameter you may use
+ :header:`If-Match` header:
+
+ .. code-block:: http
+
+ DELETE /recipes/FishStew HTTP/1.1
+ Accept: application/json
+ If-Match: 1-9c65296036141e575d32ba9c034dd3ee
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ 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 (Erlang/OTP)
+
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
+ }
.. http:copy:: /{db}/{docid}
- :synopsis: Copies the document within the same database
-
- The :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
- :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
- :config:option:`commit policy <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 URI
- :>json string id: Document 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 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
-
- **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-e86fdf912560c2321a5fcefc6264e6d9"
- Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs_Italian",
- "ok": true,
- "rev": "1-e86fdf912560c2321a5fcefc6264e6d9"
- }
-
+ :synopsis: Copies the document within the same database
+
+ The :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
+ :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
+ :config:option:`commit policy <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 URI
+ :>json string id: Document 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 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
+
+ **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-e86fdf912560c2321a5fcefc6264e6d9"
+ Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
+ Server: CouchDB (Erlang/OTP)
+
+ {
+ "id": "SpaghettiWithMeatballs_Italian",
+ "ok": true,
+ "rev": "1-e86fdf912560c2321a5fcefc6264e6d9"
+ }
.. _api/doc/attachments:
Attachments
------------
+===========
-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.
+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 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:
@@ -411,92 +413,91 @@ information objects with next structure:
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 if ``content_type`` is in :config:option:`list of compressible types
- <attachments/compressible_types>` when the attachment was added and the
+ Available if ``content_type`` is in :config:option:`list of compressible
+ types <attachments/compressible_types>` when the attachment was added and the
following query parameters are specified:
- - ``att_encoding_info=true`` when querying a document
- - ``att_encoding_info=true&include_docs=true`` when querying a
- :ref:`changes feed <api/db/changes>` or a :ref:`view <api/ddoc/view>`
+ - ``att_encoding_info=true`` when querying a document
+ - ``att_encoding_info=true&include_docs=true`` when querying a
+ :ref:`changes feed <api/db/changes>` or a :ref:`view <api/ddoc/view>`
- **encoding** (*string*): Compression codec. Available if ``content_type`` is
in :config:option:`list of compressible types
<attachments/compressible_types>` when the attachment was added and the
following query parameters are specified:
- - ``att_encoding_info=true`` when querying a document
- - ``att_encoding_info=true&include_docs=true`` when querying a
- :ref:`changes feed <api/db/changes>` or a :ref:`view <api/ddoc/view>`
+ - ``att_encoding_info=true`` when querying a document
+ - ``att_encoding_info=true&include_docs=true`` when querying a
+ :ref:`changes feed <api/db/changes>` or a :ref:`view <api/ddoc/view>`
-- **length** (*number*): Real attachment size in bytes. Not available if attachment
- content requested
+- **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 /recipes/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_attachments": {
- "grandma_recipe.txt": {
- "content_type": "text/plain",
- "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
- "length": 1872,
- "revpos": 4,
- "stub": true
- },
- "my_recipe.txt": {
- "content_type": "text/plain",
- "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
- "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
+ 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 (Erlang/OTP)
+
+ {
+ "_attachments": {
+ "grandma_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
+ "length": 1872,
+ "revpos": 4,
+ "stub": true
+ },
+ "my_recipe.txt": {
+ "content_type": "text/plain",
+ "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
+ "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"
+ }
.. _api/doc/retrieving-deleted-documents:
Retrieving Attachments Content
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
It's possible to retrieve document with all attached files content by using
``attachements=true`` query parameter:
@@ -505,40 +506,40 @@ It's possible to retrieve document with all attached files content by using
.. code-block:: http
- GET /db/pixel?attachments=true HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /db/pixel?attachments=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_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"
- }
+ 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 (Erlang/OTP)
+
+ {
+ "_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"
+ }
Or retrieve attached files content since specific revision using ``atts_since``
query parameter:
@@ -547,59 +548,58 @@ query parameter:
.. code-block:: http
- GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22] HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22] HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_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"
- }
+ 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 (Erlang/OTP)
+ {
+ "_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"
+ }
Efficient Multiple Attachments Retrieving
-`````````````````````````````````````````
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As you had noted above, retrieving document with ``attachements=true`` returns
large JSON object where all attachments are included. While you document and
@@ -613,135 +613,133 @@ To solve this problem, CouchDB allows to get documents in
.. code-block:: http
- GET /recipes/secret?attachments=true HTTP/1.1
- Accept: multipart/related
- Host: localhost:5984
+ GET /recipes/secret?attachments=true HTTP/1.1
+ Accept: multipart/related
+ Host: localhost:5984
**Response**:
.. code-block:: http
- HTTP/1.1 200 OK
- Content-Length: 538
- Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
- Date: Sat, 28 Sep 2013 08:08:22 GMT
- ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
- Server: CouchDB (Erlang OTP)
+ HTTP/1.1 200 OK
+ Content-Length: 538
+ Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
+ Date: Sat, 28 Sep 2013 08:08:22 GMT
+ ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
+ Server: CouchDB (Erlang OTP)
- --e89b3e29388aef23453450d10e5aaed0
- Content-Type: application/json
+ --e89b3e29388aef23453450d10e5aaed0
+ Content-Type: application/json
- {"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
- --e89b3e29388aef23453450d10e5aaed0
- Content-Disposition: attachment; filename="recipe.txt"
- Content-Type: text/plain
- Content-Length: 86
+ {"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
+ --e89b3e29388aef23453450d10e5aaed0
+ Content-Disposition: attachment; filename="recipe.txt"
+ Content-Type: text/plain
+ Content-Length: 86
- 1. Take R
- 2. Take E
- 3. Mix with L
- 4. Add some A
- 5. Serve with X
+ 1. Take R
+ 2. Take E
+ 3. Mix with L
+ 4. Add some A
+ 5. Serve with X
- --e89b3e29388aef23453450d10e5aaed0--
+ --e89b3e29388aef23453450d10e5aaed0--
In this response the document contains only attachments stub information and
quite short while all attachments goes as separate entities which reduces
-memory footprint and processing overhead (you'd noticed, that attachment content
-goes as raw data, not in base64 encoding, right?).
-
+memory footprint and processing overhead (you'd noticed, that attachment
+content goes as raw data, not in base64 encoding, right?).
Retrieving Attachments Encoding Info
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------------
-By using ``att_encoding_info=true`` query parameter you may retrieve information
-about compressed attachments size and used codec.
+By using ``att_encoding_info=true`` query parameter you may retrieve
+information about compressed attachments size and used codec.
**Request**:
.. code-block:: http
- GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_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
+ 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 (Erlang/OTP)
+ {
+ "_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"
+ }
Creating Multiple Attachments
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-----------------------------
To create a document with multiple attachments with single request you need
just inline base64 encoded attachments data into the document body:
.. code-block:: javascript
- {
- "_id":"multiple_attachments",
- "_attachments":
{
- "foo.txt":
+ "_id":"multiple_attachments",
+ "_attachments":
{
- "content_type":"text\/plain",
- "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
- },
-
- "bar.txt":
- {
- "content_type":"text\/plain",
- "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ "foo.txt":
+ {
+ "content_type":"text\/plain",
+ "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ },
+
+ "bar.txt":
+ {
+ "content_type":"text\/plain",
+ "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
+ }
}
}
- }
Alternatively, you can upload a document with attachments more efficiently in
:mimetype:`multipart/related` format. This avoids having to Base64-encode
@@ -760,62 +758,61 @@ The subsequent MIME bodies are the attachments.
.. code-block:: http
- PUT /temp/somedoc HTTP/1.1
- Accept: application/json
- Content-Length: 372
- Content-Type: multipart/related;boundary="abc123"
- Host: localhost:5984
- User-Agent: HTTPie/0.6.0
-
- --abc123
- Content-Type: application/json
-
- {
- "body": "This is a body.",
- "_attachments": {
- "foo.txt": {
- "follows": true,
- "content_type": "text/plain",
- "length": 21
- },
- "bar.txt": {
- "follows": true,
- "content_type": "text/plain",
- "length": 20
- }
- }
- }
+ PUT /temp/somedoc HTTP/1.1
+ Accept: application/json
+ Content-Length: 372
+ Content-Type: multipart/related;boundary="abc123"
+ Host: localhost:5984
+ User-Agent: HTTPie/0.6.0
- --abc123
+ --abc123
+ Content-Type: application/json
+
+ {
+ "body": "This is a body.",
+ "_attachments": {
+ "foo.txt": {
+ "follows": true,
+ "content_type": "text/plain",
+ "length": 21
+ },
+ "bar.txt": {
+ "follows": true,
+ "content_type": "text/plain",
+ "length": 20
+ }
+ }
+ }
+
+ --abc123
- this is 21 chars long
- --abc123
+ this is 21 chars long
+ --abc123
- this is 20 chars lon
- --abc123--
+ this is 20 chars lon
+ --abc123--
**Response**:
.. code-block:: http
- HTTP/1.1 201 Created
- Cache-Control: must-revalidate
- Content-Length: 72
- Content-Type: application/json
- Date: Sat, 28 Sep 2013 09:13:24 GMT
- ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
- Location: http://localhost:5984/temp/somedoc
- Server: CouchDB (Erlang OTP)
-
- {
- "id": "somedoc",
- "ok": true,
- "rev": "1-5575e26acdeb1df561bb5b70b26ba151"
- }
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 72
+ Content-Type: application/json
+ Date: Sat, 28 Sep 2013 09:13:24 GMT
+ ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
+ Location: http://localhost:5984/temp/somedoc
+ Server: CouchDB (Erlang OTP)
+ {
+ "id": "somedoc",
+ "ok": true,
+ "rev": "1-5575e26acdeb1df561bb5b70b26ba151"
+ }
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:
@@ -824,47 +821,46 @@ the ``revs=true`` parameter to the request URL:
.. code-block:: http
- GET /recipes/SpaghettiWithMeatballs?revs=true HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/SpaghettiWithMeatballs?revs=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_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"
- }
+ 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 (Erlang/OTP)
+ {
+ "_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"
+ }
The returned JSON structure includes the original document, including a
``_revisions`` structure that includes the revision information in next form:
@@ -873,78 +869,76 @@ The returned JSON structure includes the original document, including a
(latest first)
- **start** (*number*): Prefix number for the latest revision
-
Obtaining an Extended Revision History
---------------------------------------
+======================================
-You can get additional information about the revisions for a given
-document by supplying the ``revs_info`` argument to the query:
+You can get additional information about the revisions for a given document by
+supplying the ``revs_info`` argument to the query:
**Request**:
.. code-block:: http
- GET /recipes/SpaghettiWithMeatballs?revs_info=true HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/SpaghettiWithMeatballs?revs_info=true HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_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"
- }
+ 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 (Erlang/OTP)
+ {
+ "_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"
+ }
The returned document contains ``_revs_info`` field with extended revision
information, including the availability and status of each revision. This array
@@ -959,9 +953,8 @@ field contains objects with following structure:
- ``missing``: Revision is not available
- ``deleted``: Revision belongs to deleted document
-
Obtaining a Specific Revision
------------------------------
+=============================
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
@@ -972,65 +965,64 @@ requested.
.. code-block:: http
- GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_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"
- }
+ 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 (Erlang/OTP)
+ {
+ "_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"
+ }
Retrieving Deleted Documents
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------
CouchDB doesn't actually deletes documents via :delete:`/{db}/{docid}`.
-Instead of this, it leaves tombstone with very basic information about document.
-If you just :get:`/{db}/{docid}` CouchDB returns :statuscode:`404`
+Instead of this, it leaves tombstone with very basic information about
+document. If you just :get:`/{db}/{docid}` CouchDB returns :statuscode:`404`
response:
**Request**:
.. code-block:: http
- GET /recipes/FishStew HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/FishStew HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
+ 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 (Erlang/OTP)
- {
- "error": "not_found",
- "reason": "deleted"
- }
+ {
+ "error": "not_found",
+ "reason": "deleted"
+ }
However, you may retrieve document's tombstone by using ``rev`` query parameter
with :get:`/{db}/{docid}` request:
@@ -1039,31 +1031,30 @@ with :get:`/{db}/{docid}` request:
.. code-block:: http
- GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20 HTTP/1.1
- Accept: application/json
- Host: localhost:5984
+ GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20 HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "_deleted": true,
- "_id": "FishStew",
- "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
- }
+ 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 (Erlang/OTP)
+ {
+ "_deleted": true,
+ "_id": "FishStew",
+ "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
+ }
Updating an Existing Document
------------------------------
+=============================
To update an existing document you must specify the current revision
number within the ``_rev`` parameter.
@@ -1072,135 +1063,132 @@ number within the ``_rev`` parameter.
.. code-block:: http
- 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"
- }
-
-Alternatively, you can supply the current revision number in the
-``If-Match`` HTTP header of the request:
+ 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"
+ }
+
+Alternatively, you can supply the current revision number in the ``If-Match``
+HTTP header of the request:
.. code-block:: http
- PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- Content-Length: 258
- Content-Type: application/json
- If-Match: 1-917fa2381192822767f010b95b45325b
- Host: localhost:5984
-
- {
- "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"
- }
+ PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
+ Accept: application/json
+ Content-Length: 258
+ Content-Type: application/json
+ If-Match: 1-917fa2381192822767f010b95b45325b
+ Host: localhost:5984
+ {
+ "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"
+ }
**Response**:
.. code-block:: http
- 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 (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs",
- "ok": true,
- "rev": "2-790895a73b63fb91dd863388398483dd"
- }
+ 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 (Erlang/OTP)
+ {
+ "id": "SpaghettiWithMeatballs",
+ "ok": true,
+ "rev": "2-790895a73b63fb91dd863388398483dd"
+ }
Copying from a Specific Revision
---------------------------------
+================================
-To copy *from* a specific version, use the ``rev`` argument to the query
-string or :header:`If-Match`:
+To copy *from* a specific version, use the ``rev`` argument to the query string
+or :header:`If-Match`:
**Request**:
.. code-block:: http
- COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
- Accept: application/json
- Destination: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
- If-Match: 1-917fa2381192822767f010b95b45325b
- Host: localhost:5984
+ 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 (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs_Original",
- "ok": true,
- "rev": "1-917fa2381192822767f010b95b45325b"
- }
+ 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 (Erlang/OTP)
+ {
+ "id": "SpaghettiWithMeatballs_Original",
+ "ok": true,
+ "rev": "1-917fa2381192822767f010b95b45325b"
+ }
Copying to an Existing Document
--------------------------------
+===============================
-To copy to an existing document, you must specify the current revision
-string for the target document by appending the ``rev`` parameter to the
+To copy to an existing document, you must specify the current revision string
+for the target document by appending the ``rev`` parameter to the
:header:`Destination` header string.
**Request**:
.. code-block:: http
- 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
+ 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
**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: "2-62e778c9ec09214dd685a981dcc24074""
- Location: http://localhost:5984/recipes_old/SpaghettiWithMeatballs_Original
- Server: CouchDB (Erlang/OTP)
-
- {
- "id": "SpaghettiWithMeatballs_Original",
- "ok": true,
- "rev": "2-62e778c9ec09214dd685a981dcc24074"
- }
+ 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 (Erlang/OTP)
+
+ {
+ "id": "SpaghettiWithMeatballs_Original",
+ "ok": true,
+ "rev": "2-62e778c9ec09214dd685a981dcc24074"
+ }
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/document/index.rst
----------------------------------------------------------------------
diff --git a/src/api/document/index.rst b/src/api/document/index.rst
index 8e6b135..6d5160f 100644
--- a/src/api/document/index.rst
+++ b/src/api/document/index.rst
@@ -10,7 +10,6 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-
.. _api/document:
=========
@@ -20,6 +19,5 @@ Documents
Details on how to create, read, update and delete documents within a database.
.. toctree::
-
- common
- attachments
+ common
+ attachments
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/index.rst
----------------------------------------------------------------------
diff --git a/src/api/index.rst b/src/api/index.rst
index 2449471..b986d61 100644
--- a/src/api/index.rst
+++ b/src/api/index.rst
@@ -16,27 +16,26 @@
API Reference
=============
-The components of the API URL path help determine the part of the
-CouchDB server that is being accessed. The result is the structure of
-the URL request both identifies and effectively describes the area of
-the database you are accessing.
+The components of the API URL path help determine the part of the CouchDB
+server that is being accessed. The result is the structure of the URL request
+both identifies and effectively describes the area of the database you are
+accessing.
-As with all URLs, the individual components are separated by a forward
-slash.
+As with all URLs, the individual components are separated by a forward slash.
-As a general rule, URL components and JSON fields starting with the
-``_`` (underscore) character represent a special component or entity
-within the server or returned object. For example, the URL fragment
-``/_all_dbs`` gets a list of all of the databases in a CouchDB instance.
+As a general rule, URL components and JSON fields starting with the ``_``
+(underscore) character represent a special component or entity within the
+server or returned object. For example, the URL fragment ``/_all_dbs`` gets a
+list of all of the databases in a CouchDB instance.
This reference is structured according to the URL structure, as below.
.. toctree::
- :maxdepth: 2
-
- basics
- server/index
- database/index
- document/index
- ddoc/index
- local
+ :maxdepth: 2
+
+ basics
+ server/index
+ database/index
+ document/index
+ ddoc/index
+ local
http://git-wip-us.apache.org/repos/asf/couchdb-documentation/blob/25273e7a/src/api/local.rst
----------------------------------------------------------------------
diff --git a/src/api/local.rst b/src/api/local.rst
index 3615c2e..2caddd8 100644
--- a/src/api/local.rst
+++ b/src/api/local.rst
@@ -16,20 +16,19 @@
Local (non-replicating) Documents
=================================
-The Local (non-replicating) document interface allows you to create
-local documents that are not replicated to other databases. These
-documents can be used to hold configuration or other information that is
-required specifically on the local CouchDB instance.
+The Local (non-replicating) document interface allows you to create local
+documents that are not replicated to other databases. These documents can be
+used to hold configuration or other information that is required specifically
+on the local CouchDB instance.
Local documents have the following limitations:
-- Local documents are not replicated to other databases.
+- Local documents are not replicated to other databases.
-- The ID of the local document must be known for the document to
- accessed. You cannot obtain a list of local documents from the
- database.
+- The ID of the local document must be known for the document to accessed. You
+ cannot obtain a list of local documents from the database.
-- Local documents are not output by views, or the :ref:`api/db/all_docs` view.
+- Local documents are not output by views, or the :ref:`api/db/all_docs` view.
Local documents can be used when you want to store configuration or
other information for the current (local) instance of a given database.
@@ -56,29 +55,29 @@ A list of the available methods and URL paths are provided below:
========================
.. http:get:: /{db}/_local/{docid}
- :synopsis: Returns the latest revision of the local document
+ :synopsis: Returns the latest revision of the local document
- 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 :get:`/{db}/{docid}`.
+ 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 :get:`/{db}/{docid}`.
.. http:put:: /{db}/_local/{docid}
- :synopsis: Inserts a new version of the local document
+ :synopsis: Inserts a new version of the local document
- 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 :put:`/{db}/{docid}`.
+ 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 :put:`/{db}/{docid}`.
.. http:delete:: /{db}/_local/{docid}
- :synopsis: Deletes the local document
+ :synopsis: Deletes the local document
- 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 :delete:`/{db}/{docid}`.
+ 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 :delete:`/{db}/{docid}`.
.. http:copy:: /{db}/_local/{docid}
- :synopsis: Copies the local document within the same database
+ :synopsis: Copies the local document within the same database
- 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 :copy:`/{db}/{docid}`.
+ 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 :copy:`/{db}/{docid}`.