Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 5387CCC8D for ; Fri, 28 Nov 2014 21:00:05 +0000 (UTC) Received: (qmail 97624 invoked by uid 500); 28 Nov 2014 21:00:04 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 97482 invoked by uid 500); 28 Nov 2014 21:00:04 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 96516 invoked by uid 99); 28 Nov 2014 21:00:04 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 28 Nov 2014 21:00:04 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id BE6EB8B698E; Fri, 28 Nov 2014 21:00:03 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: robertkowalski@apache.org To: commits@couchdb.apache.org Date: Fri, 28 Nov 2014 21:00:21 -0000 Message-Id: <4e014f19e1604f6ca72846b758d76e97@git.apache.org> In-Reply-To: <73dbd4c3aedd405d98e87fed3b3c1cb9@git.apache.org> References: <73dbd4c3aedd405d98e87fed3b3c1cb9@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [19/47] couchdb commit: updated refs/heads/enable-csp-default to dbd38a1 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 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 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 - :
`. Possible values - are: ``false`` and ``true``. *Optional* - :query string batch: Stores document in :ref:`batch mode - ` 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 ` - - .. 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 - :
`. Possible values - are: ``false`` and ``true``. *Optional* - :query string rev: Actual document's revision - :query string batch: Stores document in :ref:`batch mode - ` 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 - :
`. Possible values - are: ``false`` and ``true``. *Optional* - :query string rev: Revision to copy from. *Optional* - :query string batch: Stores document in :ref:`batch mode - ` 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 ` or a :ref:`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 - ` 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 ` or a :ref:`view ` - -- **encoding** (*string*): Compression codec. Available if ``content_type`` is - in :config:option:`list of 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 ` or a :ref:`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 ` 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 -`. Also it's possible to make cookies -:config:option:`persistent ` - -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: - -``/_session`` -------------- - -.. http:post:: /_session - :synopsis: Authenticates user by Cookie-based user login - - Initiates new session for specified user credentials by providing `Cookie` - value. - - :
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 `: - username; -- :config:option:`X-Auth-CouchDB-Roles `: - list of user roles separated by a comma (``,``); -- :config:option:`X-Auth-CouchDB-Token `: - authentication token. Optional, but strongly recommended to - :config:option:`force token be required ` - 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 ` -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 `, 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 ` resource to ensure -that authentication was successful and the target CouchDB username is correct. -Change the target URL to request required resource.