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 2014/10/16 11:09:23 UTC
[11/14] Documentation was moved to couchdb-documentation repository
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/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
deleted file mode 100644
index bdd6702..0000000
--- a/share/doc/src/api/document/common.rst
+++ /dev/null
@@ -1,1206 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. 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.
-
- 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.
-
- Adding any of the query arguments (see :get:`/{db}/{docid}`), then the
- resulting HTTP Headers will correspond to what would be returned.
-
- :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
-
- **Request**:
-
- .. code-block:: http
-
- GET /db/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: "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"
- }
-
-.. 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"
- }
-
-.. 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.
-
- .. seealso::
- :ref:`Retrieving Deleted Documents <api/doc/retrieving-deleted-documents>`
-
- .. note::
- CouchDB doesn't actually delete documents. The reason is the need to track
- them correctly during the replication process between databases to prevent
- accidental document recovery for any previous state.
-
- :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"
- }
-
-
-.. _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.
-
-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
- is requested by using the following query parameters:
-
- - ``attachments=true`` when querying a document
- - ``attachments=true&include_docs=true`` when querying a
- :ref:`changes feed <api/db/changes>` or a :ref:`view <api/ddoc/view>`
- - ``atts_since``.
-
-- **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 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>`
-
-- **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>`
-
-- **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
-
-**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"
- }
-
-.. _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:
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-Or retrieve attached files content since specific revision using ``atts_since``
-query parameter:
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-
-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
-files are smaller it's ok, but if you have attached something bigger like media
-files (audio/video), parsing such response might be very expensive.
-
-To solve this problem, CouchDB allows to get documents in
-:mimetype:`multipart/related` format:
-
-**Request**:
-
-.. code-block:: http
-
- 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)
-
- --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
-
- 1. Take R
- 2. Take E
- 3. Mix with L
- 4. Add some A
- 5. Serve with X
-
- --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?).
-
-
-Retrieving Attachments Encoding Info
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-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
-
-**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"
- }
-
-
-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":
- {
- "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
-the attachments, saving CPU and bandwidth. To do this, set the
-:header:`Content-Type` header of the :put:`/{db}/{docid}` request to
-:mimetype:`multipart/related`.
-
-The first MIME body is the document itself, which should have its own
-:header:`Content-Type` of :mimetype:`application/json"`. It also should
-include an ``_attachments`` metadata object in which each attachment object
-has a key ``follows`` with value ``true``.
-
-The subsequent MIME bodies are the attachments.
-
-**Request**:
-
-.. 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
- }
- }
- }
-
- --abc123
-
- this is 21 chars long
- --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"
- }
-
-
-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:
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-
-The returned JSON structure includes the original document, including a
-``_revisions`` structure that includes the revision information in next form:
-
-- **ids** (*array*): Array of valid revision IDs, in reverse order
- (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:
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-
-The returned document contains ``_revs_info`` field with extended revision
-information, including the availability and status of each revision. This array
-field contains objects with following structure:
-
-- **rev** (*string*): Full revision string
-- **status** (*string*): Status of the revision.
- Maybe one of:
-
- - ``available``: Revision is available for retrieving with `rev` query
- parameter
- - ``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
-be returned, including a ``_rev`` field specifying the revision that was
-requested.
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-
-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`
-response:
-
-**Request**:
-
-.. code-block:: http
-
- 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)
-
- {
- "error": "not_found",
- "reason": "deleted"
- }
-
-However, you may retrieve document's tombstone by using ``rev`` query parameter
-with :get:`/{db}/{docid}` request:
-
-**Request**:
-
-.. code-block:: http
-
- 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"
- }
-
-
-Updating an Existing Document
------------------------------
-
-To update an existing document you must specify the current revision
-number within the ``_rev`` parameter.
-
-**Request**:
-
-.. 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:
-
-.. 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"
- }
-
-
-**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"
- }
-
-
-Copying from a Specific Revision
---------------------------------
-
-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
-
-**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"
- }
-
-
-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
-: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
-
-**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://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/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
deleted file mode 100644
index 8e6b135..0000000
--- a/share/doc/src/api/document/index.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-
-.. _api/document:
-
-=========
-Documents
-=========
-
-Details on how to create, read, update and delete documents within a database.
-
-.. toctree::
-
- common
- attachments
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/index.rst b/share/doc/src/api/index.rst
deleted file mode 100644
index 2449471..0000000
--- a/share/doc/src/api/index.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api:
-
-=============
-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.
-
-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.
-
-This reference is structured according to the URL structure, as below.
-
-.. toctree::
- :maxdepth: 2
-
- basics
- server/index
- database/index
- document/index
- ddoc/index
- local
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
deleted file mode 100644
index 3615c2e..0000000
--- a/share/doc/src/api/local.rst
+++ /dev/null
@@ -1,84 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api/local:
-
-=================================
-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.
-
-Local documents have the following limitations:
-
-- 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.
-
-- 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.
-
-A list of the available methods and URL paths are provided below:
-
-+--------+-------------------------+-------------------------------------------+
-| Method | Path | Description |
-+========+=========================+===========================================+
-| GET | /db/_local/id | Returns the latest revision of the |
-| | | non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| PUT | /db/_local/id | Inserts a new version of the |
-| | | non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| DELETE | /db/_local/id | Deletes the non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-| COPY | /db/_local/id | Copies the non-replicated document |
-+--------+-------------------------+-------------------------------------------+
-
-.. _api/local/doc:
-
-``/db/_local/id``
-========================
-
-.. http:get:: /{db}/_local/{docid}
- :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}`.
-
-.. http:put:: /{db}/_local/{docid}
- :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}`.
-
-.. http:delete:: /{db}/_local/{docid}
- :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}`.
-
-.. http:copy:: /{db}/_local/{docid}
- :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}`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/cdac7299/share/doc/src/api/server/authn.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/server/authn.rst b/share/doc/src/api/server/authn.rst
deleted file mode 100644
index 076bfdb..0000000
--- a/share/doc/src/api/server/authn.rst
+++ /dev/null
@@ -1,452 +0,0 @@
-.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
-.. use this file except in compliance with the License. You may obtain a copy of
-.. the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-.. License for the specific language governing permissions and limitations under
-.. the License.
-
-.. _api/auth:
-
-==============
-Authentication
-==============
-
-Interfaces for obtaining session and authorization data.
-
-.. note:: We're also strongly recommend you to
- :ref:`setup SSL <config/ssl>` to improve all authentication methods security.
-
-
-.. _api/auth/basic:
-
-Basic Authentication
-====================
-
-`Basic authentication`_ (:rfc:`2617`) is a quick and simple way to authenticate
-with CouchDB. The main drawback is the need to send user credentials with each
-request which may be insecure and could hurt operation performance (since
-CouchDB must compute password hash with every request):
-
-**Request**:
-
-.. code-block:: http
-
- GET / HTTP/1.1
- Accept: application/json
- Authorization: Basic cm9vdDpyZWxheA==
- Host: localhost:5984
-
-**Response**:
-
-.. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 177
- Content-Type: application/json
- Date: Mon, 03 Dec 2012 00:44:47 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "couchdb":"Welcome",
- "uuid":"0a959b9b8227188afc2ac26ccdf345a6",
- "version":"1.3.0",
- "vendor": {
- "version":"1.3.0",
- "name":"The Apache Software Foundation"
- }
- }
-
-.. _Basic authentication: http://en.wikipedia.org/wiki/Basic_access_authentication
-
-
-.. _api/auth/cookie:
-
-Cookie Authentication
-=====================
-
-For cookie authentication (:rfc:`2109`) CouchDB generates a token that the
-client can use for the next few requests to CouchDB. Tokens are valid until
-a timeout. When CouchDB sees a valid token in a subsequent request, it will
-authenticate user by this token without requesting the password again. By
-default, cookies are valid for 10 minutes, but it's :config:option:`adjustable
-<couch_httpd_auth/timeout>`. Also it's possible to make cookies
-:config:option:`persistent <couch_httpd_auth/allow_persistent_cookies>`
-
-To obtain the first token and thus authenticate a user for the first time, the
-`username` and `password` must be sent to the :ref:`_session API
-<api/auth/session>`.
-
-.. _api/auth/session:
-
-``/_session``
--------------
-
-.. http:post:: /_session
- :synopsis: Authenticates user by Cookie-based user login
-
- Initiates new session for specified user credentials by providing `Cookie`
- value.
-
- :<header Content-Type: - :mimetype:`application/x-www-form-urlencoded`
- - :mimetype:`application/json`
- :query string next: Enforces redirect after successful login to the specified
- location. This location is relative from server root. *Optional*.
- :form name: User name
- :form password: Password
- :>header Set-Cookie: Authorization token
- :>json boolean ok: Operation status
- :>json string name: Username
- :>json array roles: List of user roles
- :code 200: Successfully authenticated
- :code 302: Redirect after successful authentication
- :code 401: Username or password wasn't recognized
-
- **Request**:
-
- .. code-block:: http
-
- POST /_session HTTP/1.1
- Accept: application/json
- Content-Length: 24
- Content-Type: application/x-www-form-urlencoded
- Host: localhost:5984
-
- name=root&password=relax
-
- It's also possible to send data as JSON:
-
- .. code-block:: http
-
- POST /_session HTTP/1.1
- Accept: application/json
- Content-Length: 37
- Content-Type: application/json
- Host: localhost:5984
-
- {
- "name": "root",
- "password": "relax"
- }
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 43
- Content-Type: application/json
- Date: Mon, 03 Dec 2012 01:23:14 GMT
- Server: CouchDB (Erlang/OTP)
- Set-Cookie: AuthSession=cm9vdDo1MEJCRkYwMjq0LO0ylOIwShrgt8y-UkhI-c6BGw; Version=1; Path=/; HttpOnly
-
- {"ok":true,"name":"root","roles":["_admin"]}
-
- If ``next`` query parameter was provided the response will trigger redirection
- to the specified location in case of successful authentication:
-
- **Request**:
-
- .. code-block:: http
-
- POST /_session?next=/blog/_design/sofa/_rewrite/recent-posts HTTP/1.1
- Accept: application/json
- Content-Type: application/x-www-form-urlencoded
- Host: localhost:5984
-
- name=root&password=relax
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 302 Moved Temporarily
- Cache-Control: must-revalidate
- Content-Length: 43
- Content-Type: application/json
- Date: Mon, 03 Dec 2012 01:32:46 GMT
- Location: http://localhost:5984/blog/_design/sofa/_rewrite/recent-posts
- Server: CouchDB (Erlang/OTP)
- Set-Cookie: AuthSession=cm9vdDo1MEJDMDEzRTp7Vu5GKCkTxTVxwXbpXsBARQWnhQ; Version=1; Path=/; HttpOnly
-
- {"ok":true,"name":null,"roles":["_admin"]}
-
-
-.. http:get:: /_session
- :synopsis: Returns Cookie-based login user information
-
- Returns complete information about authenticated user.
- This information contains :ref:`userctx_object`, authentication method and
- available ones and authentication database.
-
- :query boolean basic: Accept `Basic Auth` by requesting this resource.
- *Optional*.
- :code 200: Successfully authenticated.
- :code 401: Username or password wasn't recognized.
-
- **Request**:
-
- .. code-block:: http
-
- GET /_session HTTP/1.1
- Host: localhost:5984
- Accept: application/json
- Cookie: AuthSession=cm9vdDo1MEJDMDQxRDpqb-Ta9QfP9hpdPjHLxNTKg_Hf9w
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 175
- Content-Type: application/json
- Date: Fri, 09 Aug 2013 20:27:45 GMT
- Server: CouchDB (Erlang/OTP)
- Set-Cookie: AuthSession=cm9vdDo1MjA1NTBDMTqmX2qKt1KDR--GUC80DQ6-Ew_XIw; Version=1; Path=/; HttpOnly
-
- {
- "info": {
- "authenticated": "cookie",
- "authentication_db": "_users",
- "authentication_handlers": [
- "oauth",
- "cookie",
- "default"
- ]
- },
- "ok": true,
- "userCtx": {
- "name": "root",
- "roles": [
- "_admin"
- ]
- }
- }
-
-
-.. http:delete:: /_session
- :synopsis: Logout Cookie-based user
-
- Closes user's session.
-
- :code 200: Successfully close session.
- :code 401: User wasn't authenticated.
-
- **Request**:
-
- .. code-block:: http
-
- DELETE /_session HTTP/1.1
- Accept: application/json
- Cookie: AuthSession=cm9vdDo1MjA1NEVGMDo1QXNQkqC_0Qmgrk8Fw61_AzDeXw
- Host: localhost:5984
-
- **Response**:
-
- .. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 12
- Content-Type: application/json
- Date: Fri, 09 Aug 2013 20:30:12 GMT
- Server: CouchDB (Erlang/OTP)
- Set-Cookie: AuthSession=; Version=1; Path=/; HttpOnly
-
- {
- "ok": true
- }
-
-
-.. _api/auth/proxy:
-
-Proxy Authentication
-====================
-
-.. note::
- To use this authentication method make sure that the
- ``{couch_httpd_auth, proxy_authentication_handler}`` value in added to
- the list of the active :config:option:`httpd/authentication_handlers`:
-
- .. code-block:: ini
-
- [httpd]
- authentication_handlers = {couch_httpd_oauth, oauth_authentication_handler}, {couch_httpd_auth, cookie_authentication_handler}, {couch_httpd_auth, proxy_authentication_handler}, {couch_httpd_auth, default_authentication_handler}
-
-
-`Proxy authentication` is very useful in case your application already uses
-some external authentication service and you don't want to duplicate users and
-their roles in CouchDB.
-
-This authentication method allows creation of a :ref:`userctx_object` for
-remotely authenticated user. By default, the client just need to pass specific
-headers to CouchDB with related request:
-
-- :config:option:`X-Auth-CouchDB-UserName <couch_httpd_auth/x_auth_username>`:
- username;
-- :config:option:`X-Auth-CouchDB-Roles <couch_httpd_auth/x_auth_roles>`:
- list of user roles separated by a comma (``,``);
-- :config:option:`X-Auth-CouchDB-Token <couch_httpd_auth/x_auth_token>`:
- authentication token. Optional, but strongly recommended to
- :config:option:`force token be required <couch_httpd_auth/proxy_use_secret>`
- to prevent requests from untrusted sources.
-
-**Request**:
-
-.. code-block:: http
-
- GET /_session HTTP/1.1
- Host: localhost:5984
- Accept: application/json
- Content-Type: application/json; charset=utf-8
- X-Auth-CouchDB-Roles: users,blogger
- X-Auth-CouchDB-UserName: foo
-
-**Response**:
-
-.. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control: must-revalidate
- Content-Length: 190
- Content-Type: application/json
- Date: Fri, 14 Jun 2013 10:16:03 GMT
- Server: CouchDB (Erlang/OTP)
-
- {
- "info": {
- "authenticated": "proxy",
- "authentication_db": "_users",
- "authentication_handlers": [
- "oauth",
- "cookie",
- "proxy",
- "default"
- ]
- },
- "ok": true,
- "userCtx": {
- "name": "foo",
- "roles": [
- "users",
- "blogger"
- ]
- }
- }
-
-
-Note that you don't need to request :ref:`session <api/auth/session>`
-to be authenticated by this method if all required HTTP headers are provided.
-
-
-.. _api/auth/oauth:
-
-OAuth Authentication
-====================
-
-CouchDB supports OAuth 1.0 authentication (:rfc:`5849`). OAuth provides a method
-for clients to access server resources without sharing real credentials
-(username and password).
-
-First, :ref:`configure oauth <config/oauth>`, by setting consumer and token
-with their secrets and binding token to real CouchDB username.
-
-Probably, it's not good idea to work with plain curl, let use some scripting
-language like Python:
-
-.. code-block:: python
-
- #!/usr/bin/env python2
- from oauth import oauth # pip install oauth
- import httplib
-
- URL = 'http://localhost:5984/_session'
- CONSUMER_KEY = 'consumer1'
- CONSUMER_SECRET = 'sekr1t'
- TOKEN = 'token1'
- SECRET = 'tokensekr1t'
-
- consumer = oauth.OAuthConsumer(CONSUMER_KEY, CONSUMER_SECRET)
- token = oauth.OAuthToken(TOKEN, SECRET)
- req = oauth.OAuthRequest.from_consumer_and_token(
- consumer,
- token=token,
- http_method='GET',
- http_url=URL,
- parameters={}
- )
- req.sign_request(oauth.OAuthSignatureMethod_HMAC_SHA1(), consumer,token)
-
- headers = req.to_header()
- headers['Accept'] = 'application/json'
-
- con = httplib.HTTPConnection('localhost', 5984)
- con.request('GET', URL, headers=headers)
- resp = con.getresponse()
- print resp.read()
-
-or Ruby:
-
-.. code-block:: ruby
-
- #!/usr/bin/env ruby
-
- require 'oauth' # gem install oauth
-
- URL = 'http://localhost:5984'
- CONSUMER_KEY = 'consumer1'
- CONSUMER_SECRET = 'sekr1t'
- TOKEN = 'token1'
- SECRET = 'tokensekr1t'
-
- @consumer = OAuth::Consumer.new CONSUMER_KEY,
- CONSUMER_SECRET,
- {:site => URL}
-
- @access_token = OAuth::AccessToken.new(@consumer, TOKEN, SECRET)
-
- puts @access_token.get('/_session').body
-
-
-Both snippets produces similar request and response pair:
-
-.. code-block:: http
-
- GET /_session HTTP/1.1
- Host: localhost:5984
- Accept: application/json
- Authorization: OAuth realm="", oauth_nonce="81430018", oauth_timestamp="1374561749", oauth_consumer_key="consumer1", oauth_signature_method="HMAC-SHA1", oauth_version="1.0", oauth_token="token1", oauth_signature="o4FqJ8%2B9IzUpXH%2Bk4rgnv7L6eTY%3D"
-
-.. code-block:: http
-
- HTTP/1.1 200 OK
- Cache-Control : must-revalidate
- Content-Length : 167
- Content-Type : application/json
- Date : Tue, 23 Jul 2013 06:51:15 GMT
- Server: CouchDB (Erlang/OTP)
-
-
- {
- "ok": true,
- "info": {
- "authenticated": "oauth",
- "authentication_db": "_users",
- "authentication_handlers": ["oauth", "cookie", "default"]
- },
- "userCtx": {
- "name": "couchdb_username",
- "roles": []
- }
- }
-
-There we request the :ref:`_session <api/auth/session>` resource to ensure
-that authentication was successful and the target CouchDB username is correct.
-Change the target URL to request required resource.