You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by dc...@apache.org on 2012/12/12 21:33:59 UTC
[6/34] Transmogrify Couchbase XML to .rst and support Sphinx
http://git-wip-us.apache.org/repos/asf/couchdb/blob/de115c3a/share/doc/src/api/design.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/design.rst b/share/doc/src/api/design.rst
new file mode 100644
index 0000000..38bdd0b
--- /dev/null
+++ b/share/doc/src/api/design.rst
@@ -0,0 +1,1264 @@
+.. 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-design:
+
+=======================
+Design Document Methods
+=======================
+
+In CouchDB, design documents provide the main interface for building a
+CouchDB application. The design document defines the views used to
+extract information from CouchDB through one or more views. Design
+documents are created within your CouchDB instance in the same way as
+you create database documents, but the content and definition of the
+documents is different. Design Documents are named using an ID defined
+with the design document URL path, and this URL can then be used to
+access the database contents.
+
+Views and lists operate together to provide automated (and formatted)
+output from your database.
+
+A list of the available methods and URL paths are provided below:
+
+Design Document API Calls
+
+``GET /db/_design/design-doc``
+==============================
+
+* **Method**: ``GET /db/_design/design-doc``
+* **Request**: None
+* **Response**: JSON of the existing design document
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Specify the revision to return
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: revs
+
+ * **Description**: Return a list of the revisions for the document
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Supported Values**:
+
+ * **true**: Includes the revisions
+
+ * **Argument**: revs_info
+
+ * **Description**: Return a list of detailed revision information for the
+ document
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Supported Values**:
+
+ * **true**: Includes the revisions
+
+Returns the specified design document, ``design-doc`` from the specified
+``db``. For example, to retrieve the design document ``recipes`` you
+would send the following request:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/_design/recipes
+ Content-Type: application/json
+
+The returned string will be the JSON of the design document:
+
+.. code-block:: javascript
+
+ {
+ "_id" : "_design/recipes",
+ "_rev" : "5-39f56a392b86bbee57e2138921346406"
+ "language" : "javascript",
+ "views" : {
+ "by_recipe" : {
+ "map" : "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
+ },
+ },
+ }
+
+A list of the revisions can be obtained by using the ``revs`` query
+argument, or an extended list of revisions using the ``revs_info`` query
+argument. This operates in the same way as for other documents. Fur
+further examples, see :ref:`api-get-doc`.
+
+``PUT /db/_design/design-doc``
+==============================
+
+* **Method**: ``PUT /db/_design/design-doc``
+* **Request**: JSON of the design document
+* **Response**: JSON status
+* **Admin Privileges Required**: no
+
+Upload the specified design document, ``design-doc``, to the specified
+database. The design document should follow the definition of a design
+document, as summarised in the following table.
+
+* **_id**: Design Document ID
+* **_rev**: Design Document Revision
+* **views**: View
+
+ * **viewname**: View Definition
+
+ * **map**: Map Function for View
+ * **reduce (optional)**: Reduce Function for View
+
+For more information on writing views, see :ref:`views`.
+
+``DELETE /db/_design/design-doc``
+=================================
+
+* **Method**: ``DELETE /db/_design/design-doc``
+* **Request**: None
+* **Response**: JSON of deleted design document
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **409**:
+ Supplied revision is incorrect or missing
+
+Delete an existing design document. Deleting a design document also
+deletes all of the associated view indexes, and recovers the
+corresponding space on disk for the indexes in question.
+
+To delete, you must specify the current revision of the design document
+using the ``rev`` query argument.
+
+For example:
+
+.. code-block:: http
+
+ DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
+ Content-Type: application/json
+
+The response contains the delete document ID and revision:
+
+.. code-block:: javascript
+
+ {
+ "id" : "recipe/_design/recipes"
+ "ok" : true,
+ "rev" : "3-7a05370bff53186cb5d403f861aca154",
+ }
+
+``COPY /db/_design/design-doc``
+===============================
+
+* **Method**: ``COPY /db/_design/design-doc``
+* **Request**: None
+* **Response**: JSON of the new document and revision
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Revision to copy from
+ * **Optional**: yes
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``Destination``
+
+ * **Description**: Destination document (and optional revision)
+ * **Optional**: no
+
+The ``COPY`` command (non-standard HTTP) copies an existing design
+document to a new or existing document.
+
+The source design document is specified on the request line, with the
+``Destination`` HTTP Header of the request specifying the target
+document.
+
+Copying a Design Document
+-------------------------
+
+To copy the latest version of a design document to a new document you
+specify the base document and target document:
+
+.. code-block:: http
+
+ COPY http://couchdb:5984/recipes/_design/recipes
+ Content-Type: application/json
+ Destination: /recipes/_design/recipelist
+
+The above request copies the design document ``recipes`` to the new
+design document ``recipelist``. The response is the ID and revision of
+the new document.
+
+.. code-block:: javascript
+
+ {
+ "id" : "recipes/_design/recipelist"
+ "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
+ }
+
+.. note::
+ Copying a design document does automatically reconstruct the view
+ indexes. These will be recreated, as with other views, the first
+ time the new view is accessed.
+
+Copying from a Specific Revision
+--------------------------------
+
+To copy *from* a specific version, use the ``rev`` argument to the query
+string:
+
+.. code-block:: http
+
+ COPY http://couchdb:5984/recipes/_design/recipes?rev=1-e23b9e942c19e9fb10ff1fde2e50e0f5
+ Content-Type: application/json
+ Destination: recipes/_design/recipelist
+
+The new design document will be created using the specified revision of
+the source document.
+
+Copying to an Existing Design Document
+--------------------------------------
+
+To copy to an existing document, you must specify the current revision
+string for the target document, using the ``rev`` parameter to the
+``Destination`` HTTP Header string. For example:
+
+.. code-block:: http
+
+ COPY http://couchdb:5984/recipes/_design/recipes
+ Content-Type: application/json
+ Destination: recipes/_design/recipelist?rev=1-9c65296036141e575d32ba9c034dd3ee
+
+The return value will be the new revision of the copied document:
+
+.. code-block:: javascript
+
+ {
+ "id" : "recipes/_design/recipes"
+ "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
+ }
+
+``GET /db/_design/design-doc/attachment``
+=========================================
+
+* **Method**: ``GET /db/_design/design-doc/attachment``
+* **Request**: None
+* **Response**: Returns the attachment data
+* **Admin Privileges Required**: no
+
+Returns the file attachment ``attachment`` associated with the design
+document ``/_design_/design-doc``. The raw data of the associated
+attachment is returned (just as if you were accessing a static file. The
+returned HTTP ``Content-type`` will be the same as the content type set
+when the document attachment was submitted into the database.
+
+``PUT /db/_design/design-doc/attachment``
+=========================================
+
+* **Method**: ``PUT /db/_design/design-doc/attachment``
+* **Request**: Raw document data
+* **Response**: JSON document status
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current document revision
+ * **Optional**: no
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``Content-Length``
+
+ * **Description**: Length (bytes) of the attachment being uploaded
+ * **Optional**: no
+
+ * **Header**: ``Content-Type``
+
+ * **Description**: MIME type for the uploaded attachment
+ * **Optional**: no
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+Upload the supplied content as an attachment to the specified design
+document (``/_design/design-doc``). The ``attachment`` name provided
+must be a URL encoded string. You must also supply either the ``rev``
+query argument or the ``If-Match`` HTTP header for validation, and the
+HTTP headers (to set the attacment content type). The content type is
+used when the attachment is requested as the corresponding content-type
+in the returned document header.
+
+For example, you could upload a simple text document using the following
+request:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/_design/recipes/view.css?rev=7-f7114d4d81124b223283f3e89eee043e
+ Content-Length: 39
+ Content-Type: text/plain
+
+ div.recipetitle {
+ font-weight: bold;
+ }
+
+Or by using the ``If-Match`` HTTP header:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/FishStew/basic
+ If-Match: 7-f7114d4d81124b223283f3e89eee043e
+ Content-Length: 39
+ Content-Type: text/plain
+
+ div.recipetitle {
+ font-weight: bold;
+ }
+
+The returned JSON contains the new document information:
+
+.. code-block:: javascript
+
+ {
+ "id" : "_design/recipes"
+ "ok" : true,
+ "rev" : "8-cb2b7d94eeac76782a02396ba70dfbf5",
+ }
+
+.. note::
+ Uploading an attachment updates the corresponding document revision.
+ Revisions are tracked for the parent document, not individual attachments.
+
+``DELETE /db/_design/design-doc/attachment``
+============================================
+
+* **Method**: ``DELETE /db/_design/design-doc/attachment``
+* **Request**: None
+* **Response**: JSON status
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current document revision
+ * **Optional**: no
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **200**:
+ Attachment deleted successfully
+ * **409**:
+ Supplied revision is incorrect or missing
+
+Deletes the attachment ``attachment`` to the specified
+``_design/design-doc``. You must supply the ``rev`` argument with the
+current revision to delete the attachment.
+
+For example to delete the attachment ``view.css`` from the design
+document ``recipes``:
+
+.. code-block:: http
+
+ DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
+
+The returned JSON contains the updated revision information for the
+parent document:
+
+.. code-block:: javascript
+
+ {
+ "id" : "_design/recipes"
+ "ok" : true,
+ "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
+ }
+
+``GET /db/_design/design-doc/_info``
+====================================
+
+* **Method**: ``GET /db/_design/design-doc/_info``
+* **Request**: None
+* **Response**: JSON of the design document information
+* **Admin Privileges Required**: no
+
+Obtains information about a given design document, including the index,
+index size and current status of the design document and associated
+index information.
+
+For example, to get the information for the ``recipes`` design document:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/_design/recipes/_info
+ Content-Type: application/json
+
+This returns the following JSON structure:
+
+.. code-block:: javascript
+
+ {
+ "name" : "recipes"
+ "view_index" : {
+ "compact_running" : false,
+ "updater_running" : false,
+ "language" : "javascript",
+ "purge_seq" : 10,
+ "waiting_commit" : false,
+ "waiting_clients" : 0,
+ "signature" : "fc65594ee76087a3b8c726caf5b40687",
+ "update_seq" : 375031,
+ "disk_size" : 16491
+ },
+ }
+
+The individual fields in the returned JSON structure are detailed below:
+
+* **name**: Name/ID of Design Document
+* **view_index**: View Index
+
+ * **compact_running**: Indicates whether a compaction routine is currently
+ running on the view
+ * **disk_size**: Size in bytes of the view as stored on disk
+ * **language**: Language for the defined views
+ * **purge_seq**: The purge sequence that has been processed
+ * **signature**: MD5 signature of the views for the design document
+ * **update_seq**: The update sequence of the corresponding database that
+ has been indexed
+ * **updater_running**: Indicates if the view is currently being updated
+ * **waiting_clients**: Number of clients waiting on views from this design
+ document
+ * **waiting_commit**: Indicates if there are outstanding commits to the
+ underlying database that need to processed
+
+.. _api-get-view:
+
+.. _views:
+
+``GET /db/_design/design-doc/_view/view-name``
+==============================================
+
+* **Method**: ``GET /db/_design/design-doc/_view/view-name``
+* **Request**: None
+* **Response**: JSON of the documents returned by the view
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: descending
+
+ * **Description**: Return the documents in descending by key order
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+ * **Argument**: endkey
+
+ * **Description**: Stop returning records when the specified key is reached
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: endkey_docid
+
+ * **Description**: Stop returning records when the specified document
+ ID is reached
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: group
+
+ * **Description**: Group the results using the reduce function to a
+ group or single row
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+ * **Argument**: group_level
+
+ * **Description**: Specify the group level to be used
+ * **Optional**: yes
+ * **Type**: numeric
+
+ * **Argument**: include_docs
+
+ * **Description**: Include the full content of the documents in the return
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+ * **Argument**: inclusive_end
+
+ * **Description**: Specifies whether the specified end key should be
+ included in the result
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: true
+
+ * **Argument**: key
+
+ * **Description**: Return only documents that match the specified key
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: limit
+
+ * **Description**: Limit the number of the returned documents to the
+ specified number
+ * **Optional**: yes
+ * **Type**: numeric
+
+ * **Argument**: reduce
+
+ * **Description**: Use the reduction function
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: true
+
+ * **Argument**: skip
+
+ * **Description**: Skip this number of records before starting to return
+ the results
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 0
+
+ * **Argument**: stale
+
+ * **Description**: Allow the results from a stale view to be used
+ * **Optional**: yes
+ * **Type**: string
+ * **Default**:
+ * **Supported Values**
+
+ * **ok**: Allow stale views
+
+ * **Argument**: startkey
+
+ * **Description**: Return records starting with the specified key
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: startkey_docid
+
+ * **Description**: Return records starting with the specified document ID
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: update_seq
+
+ * **Description**: Include the update sequence in the generated results
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+Executes the specified ``view-name`` from the specified ``design-doc``
+design document.
+
+Querying Views and Indexes
+--------------------------
+
+The definition of a view within a design document also creates an index
+based on the key information defined within each view. The production
+and use of the index significantly increases the speed of access and
+searching or selecting documents from the view.
+
+However, the index is not updated when new documents are added or
+modified in the database. Instead, the index is generated or updated,
+either when the view is first accessed, or when the view is accessed
+after a document has been updated. In each case, the index is updated
+before the view query is executed against the database.
+
+View indexes are updated incrementally in the following situations:
+
+- A new document has been added to the database.
+
+- A document has been deleted from the database.
+
+- A document in the database has been updated.
+
+View indexes are rebuilt entirely when the view definition changes. To
+achieve this, a 'fingerprint' of the view definition is created when the
+design document is updated. If the fingerprint changes, then the view
+indexes are entirely rebuilt. This ensures that changes to the view
+definitions are reflected in the view indexes.
+
+.. note::
+ View index rebuilds occur when one view from the same the view group
+ (i.e. all the views defined within a single a design document) has
+ been determined as needing a rebuild. For example, if if you have a
+ design document with different views, and you update the database,
+ all three view indexes within the design document will be updated.
+
+Because the view is updated when it has been queried, it can result in a
+delay in returned information when the view is accessed, especially if
+there are a large number of documents in the database and the view index
+does not exist. There are a number of ways to mitigate, but not
+completely eliminate, these issues. These include:
+
+- Create the view definition (and associated design documents) on your
+ database before allowing insertion or updates to the documents. If
+ this is allowed while the view is being accessed, the index can be
+ updated incrementally.
+
+- Manually force a view request from the database. You can do this
+ either before users are allowed to use the view, or you can access
+ the view manually after documents are added or updated.
+
+- Use the ``/db/_changes`` method to monitor for changes to the
+ database and then access the view to force the corresponding view
+ index to be updated. See :ref:`api-changes` for more information.
+
+- Use a monitor with the ``update_notification`` section of the CouchDB
+ configuration file to monitor for changes to your database, and
+ trigger a view query to force the view to be updated. For more
+ information, see :ref:`update-notifications`.
+
+None of these can completely eliminate the need for the indexes to be
+rebuilt or updated when the view is accessed, but they may lessen the
+effects on end-users of the index update affecting the user experience.
+
+Another alternative is to allow users to access a 'stale' version of the
+view index, rather than forcing the index to be updated and displaying
+the updated results. Using a stale view may not return the latest
+information, but will return the results of the view query using an
+existing version of the index.
+
+For example, to access the existing stale view ``by_recipe`` in the
+``recipes`` design document:
+
+.. code-block:: text
+
+ http://couchdb:5984/recipes/_design/recipes/_view/by_recipe?stale=ok
+
+Accessing a stale view:
+
+- Does not trigger a rebuild of the view indexes, even if there have
+ been changes since the last access.
+
+- Returns the current version of the view index, if a current version
+ exists.
+
+- Returns an empty result set if the given view index does exist.
+
+As an alternative, you use the ``update_after`` value to the ``stale``
+parameter. This causes the view to be returned as a stale view, but for
+the update process to be triggered after the view information has been
+returned to the client.
+
+In addition to using stale views, you can also make use of the
+``update_seq`` query argument. Using this query argument generates the
+view information including the update sequence of the database from
+which the view was generated. The returned value can be compared this to
+the current update sequence exposed in the database information
+(returned by :ref:`api-get-db`).
+
+Sorting Returned Rows
+---------------------
+
+Each element within the returned array is sorted using native UTF-8
+sorting according to the contents of the key portion of the emitted
+content. The basic order of output is as follows:
+
+- ``null``
+
+- ``false``
+
+- ``true``
+
+- Numbers
+
+- Text (case sensitive, lowercase first)
+
+- Arrays (according to the values of each element, in order)
+
+- Objects (according to the values of keys, in key order)
+
+You can reverse the order of the returned view information by using the
+``descending`` query value set to true. For example, Retrieving the list
+of recipes using the ``by_title`` (limited to 5 records) view:
+
+.. code-block:: javascript
+
+ {
+ "offset" : 0,
+ "rows" : [
+ {
+ "id" : "3-tiersalmonspinachandavocadoterrine",
+ "key" : "3-tier salmon, spinach and avocado terrine",
+ "value" : [
+ null,
+ "3-tier salmon, spinach and avocado terrine"
+ ]
+ },
+ {
+ "id" : "Aberffrawcake",
+ "key" : "Aberffraw cake",
+ "value" : [
+ null,
+ "Aberffraw cake"
+ ]
+ },
+ {
+ "id" : "Adukiandorangecasserole-microwave",
+ "key" : "Aduki and orange casserole - microwave",
+ "value" : [
+ null,
+ "Aduki and orange casserole - microwave"
+ ]
+ },
+ {
+ "id" : "Aioli-garlicmayonnaise",
+ "key" : "Aioli - garlic mayonnaise",
+ "value" : [
+ null,
+ "Aioli - garlic mayonnaise"
+ ]
+ },
+ {
+ "id" : "Alabamapeanutchicken",
+ "key" : "Alabama peanut chicken",
+ "value" : [
+ null,
+ "Alabama peanut chicken"
+ ]
+ }
+ ],
+ "total_rows" : 2667
+ }
+
+Requesting the same in descending order will reverse the entire view
+content. For example the request
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/_design/recipes/_view/by_title?limit=5&descending=true
+ Accept: application/json
+ Content-Type: application/json
+
+Returns the last 5 records from the view:
+
+.. code-block:: javascript
+
+ {
+ "offset" : 0,
+ "rows" : [
+ {
+ "id" : "Zucchiniinagrodolcesweet-sourcourgettes",
+ "key" : "Zucchini in agrodolce (sweet-sour courgettes)",
+ "value" : [
+ null,
+ "Zucchini in agrodolce (sweet-sour courgettes)"
+ ]
+ },
+ {
+ "id" : "Zingylemontart",
+ "key" : "Zingy lemon tart",
+ "value" : [
+ null,
+ "Zingy lemon tart"
+ ]
+ },
+ {
+ "id" : "Zestyseafoodavocado",
+ "key" : "Zesty seafood avocado",
+ "value" : [
+ null,
+ "Zesty seafood avocado"
+ ]
+ },
+ {
+ "id" : "Zabaglione",
+ "key" : "Zabaglione",
+ "value" : [
+ null,
+ "Zabaglione"
+ ]
+ },
+ {
+ "id" : "Yogurtraita",
+ "key" : "Yogurt raita",
+ "value" : [
+ null,
+ "Yogurt raita"
+ ]
+ }
+ ],
+ "total_rows" : 2667
+ }
+
+The sorting direction is applied before the filtering applied using the
+``startkey`` and ``endkey`` query arguments. For example the following
+query:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey=%22carrots%22&endkey=%22egg%22
+ Accept: application/json
+ Content-Type: application/json
+
+Will operate correctly when listing all the matching entries between
+“carrots” and ``egg``. If the order of output is reversed with the
+``descending`` query argument, the view request will return no entries:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22carrots%22&endkey=%22egg%22
+ Accept: application/json
+ Content-Type: application/json
+
+The returned result is empty:
+
+.. code-block:: javascript
+
+ {
+ "total_rows" : 26453,
+ "rows" : [],
+ "offset" : 21882
+ }
+
+The results will be empty because the entries in the view are reversed
+before the key filter is applied, and therefore the ``endkey`` of “egg”
+will be seen before the ``startkey`` of “carrots”, resulting in an empty
+list.
+
+Instead, you should reverse the values supplied to the ``startkey`` and
+``endkey`` parameters to match the descending sorting applied to the
+keys. Changing the previous example to:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?descending=true&startkey=%22egg%22&endkey=%22carrots%22
+ Accept: application/json
+ Content-Type: application/json
+
+Specifying Start and End Values
+-------------------------------
+
+.. todo:: Specifying Start and End Values
+
+The ``startkey`` and ``endkey`` query arguments can be used to specify
+the range of values to be displayed when querying the view.
+
+Using Limits and Skipping Rows
+------------------------------
+
+.. todo:: Using Limits and Skipping Rows
+
+TBC
+
+View Reduction and Grouping
+---------------------------
+
+.. todo:: View Reduction and Grouping
+
+TBC
+
+``POST /db/_design/design-doc/_view/view-name``
+===============================================
+
+* **Method**: ``POST /db/_design/design-doc/_view/view-name``
+* **Request**: List of keys to be returned from specified view
+* **Response**: JSON of the documents returned by the view
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: descending
+
+ * **Description**: Return the documents in descending by key order
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+ * **Argument**: endkey
+
+ * **Description**: Stop returning records when the specified key is reached
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: endkey_docid
+
+ * **Description**: Stop returning records when the specified document ID
+ is reached
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: group
+
+ * **Description**: Group the results using the reduce function to a group
+ or single row
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+ * **Argument**: group_level
+
+ * **Description**: Specify the group level to be used
+ * **Optional**: yes
+ * **Type**: numeric
+
+ * **Argument**: include_docs
+
+ * **Description**: Include the full content of the documents in the return
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+ * **Argument**: inclusive_end
+
+ * **Description**: Specifies whether the specified end key should be
+ included in the result
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: true
+
+ * **Argument**: key
+
+ * **Description**: Return only documents that match the specified key
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: limit
+
+ * **Description**: Limit the number of the returned documents to the
+ specified number
+ * **Optional**: yes
+ * **Type**: numeric
+
+ * **Argument**: reduce
+
+ * **Description**: Use the reduction function
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: true
+
+ * **Argument**: skip
+
+ * **Description**: Skip this number of records before starting to return
+ the results
+ * **Optional**: yes
+ * **Type**: numeric
+ * **Default**: 0
+
+ * **Argument**: stale
+
+ * **Description**: Allow the results from a stale view to be used
+ * **Optional**: yes
+ * **Type**: string
+ * **Default**:
+ * **Supported Values**:
+
+ * **ok**: Allow stale views
+
+ * **Argument**: startkey
+
+ * **Description**: Return records starting with the specified key
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: startkey_docid
+
+ * **Description**: Return records starting with the specified document ID
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: update_seq
+
+ * **Description**: Include the update sequence in the generated results
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+
+Executes the specified ``view-name`` from the specified ``design-doc``
+design document. Unlike the ``GET`` method for accessing views, the
+``POST`` method supports the specification of explicit keys to be
+retrieved from the view results. The remainder of the ``POST`` view
+functionality is identical to the :ref:`api-get-view` API.
+
+For example, the request below will return all the recipes where the key
+for the view matches either “claret” or “clear apple cider” :
+
+.. code-block:: http
+
+ POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient
+ Content-Type: application/json
+
+ {
+ "keys" : [
+ "claret",
+ "clear apple juice"
+ ]
+ }
+
+
+The returned view data contains the standard view information, but only
+where the keys match.
+
+.. code-block:: javascript
+
+ {
+ "total_rows" : 26484,
+ "rows" : [
+ {
+ "value" : [
+ "Scotch collops"
+ ],
+ "id" : "Scotchcollops",
+ "key" : "claret"
+ },
+ {
+ "value" : [
+ "Stand pie"
+ ],
+ "id" : "Standpie",
+ "key" : "clear apple juice"
+ }
+ ],
+ "offset" : 6324
+ }
+
+Multi-document Fetching
+-----------------------
+
+By combining the ``POST`` method to a given view with the
+``include_docs=true`` query argument you can obtain multiple documents
+from a database. The result is more efficient than using multiple
+:ref:`api-get-doc` requests.
+
+For example, sending the following request for ingredients matching
+“claret” and “clear apple juice”:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?include_docs=true
+ Content-Type: application/json
+
+ {
+ "keys" : [
+ "claret",
+ "clear apple juice"
+ ]
+ }
+
+Returns the full document for each recipe:
+
+.. code-block:: javascript
+
+ {
+ "offset" : 6324,
+ "rows" : [
+ {
+ "doc" : {
+ "_id" : "Scotchcollops",
+ "_rev" : "1-bcbdf724f8544c89697a1cbc4b9f0178",
+ "cooktime" : "8",
+ "ingredients" : [
+ {
+ "ingredient" : "onion",
+ "ingredtext" : "onion, peeled and chopped",
+ "meastext" : "1"
+ },
+ ...
+ ],
+ "keywords" : [
+ "cook method.hob, oven, grill@hob",
+ "diet@wheat-free",
+ "diet@peanut-free",
+ "special collections@classic recipe",
+ "cuisine@british traditional",
+ "diet@corn-free",
+ "diet@citrus-free",
+ "special collections@very easy",
+ "diet@shellfish-free",
+ "main ingredient@meat",
+ "occasion@christmas",
+ "meal type@main",
+ "diet@egg-free",
+ "diet@gluten-free"
+ ],
+ "preptime" : "10",
+ "servings" : "4",
+ "subtitle" : "This recipe comes from an old recipe book of 1683 called 'The Gentlewoman's Kitchen'. This is an excellent way of making a rich and full-flavoured meat dish in a very short time.",
+ "title" : "Scotch collops",
+ "totaltime" : "18"
+ },
+ "id" : "Scotchcollops",
+ "key" : "claret",
+ "value" : [
+ "Scotch collops"
+ ]
+ },
+ {
+ "doc" : {
+ "_id" : "Standpie",
+ "_rev" : "1-bff6edf3ca2474a243023f2dad432a5a",
+ "cooktime" : "92",
+ "ingredients" : [
+ ... ],
+ "keywords" : [
+ "diet@dairy-free",
+ "diet@peanut-free",
+ "special collections@classic recipe",
+ "cuisine@british traditional",
+ "diet@corn-free",
+ "diet@citrus-free",
+ "occasion@buffet party",
+ "diet@shellfish-free",
+ "occasion@picnic",
+ "special collections@lunchbox",
+ "main ingredient@meat",
+ "convenience@serve with salad for complete meal",
+ "meal type@main",
+ "cook method.hob, oven, grill@hob / oven",
+ "diet@cow dairy-free"
+ ],
+ "preptime" : "30",
+ "servings" : "6",
+ "subtitle" : "Serve this pie with pickled vegetables and potato salad.",
+ "title" : "Stand pie",
+ "totaltime" : "437"
+ },
+ "id" : "Standpie",
+ "key" : "clear apple juice",
+ "value" : [
+ "Stand pie"
+ ]
+ }
+ ],
+ "total_rows" : 26484
+ }
+
+``GET /db/_design/design-doc/_show/show-name``
+===============================================
+
+.. todo:: GET /db/_design/design-doc/_show/show-name
+
+* **Method**: ``GET /db/_design/design-doc/_show/show-name``
+* **Request**: None
+* **Response**: Returns the result of the show
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: details
+
+ * **Description**: Indicates whether details should be included
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: format
+
+ * **Description**: Format of the returned information
+ * **Optional**: yes
+ * **Type**: string
+
+``POST /db/_design/design-doc/_show/show-name/doc``
+===================================================
+
+.. todo:: POST /db/_design/design-doc/_show/show-name/doc
+
+* **Method**: ``POST /db/_design/design-doc/_show/show-name``
+* **Request**: Custom data
+* **Response**: Returns the result of the show
+* **Admin Privileges Required**: no
+
+``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
+=========================================================================
+
+.. todo:: GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name
+
+* **Method**: ``GET /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
+
+``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
+==========================================================================
+
+.. todo:: POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name
+
+* **Method**: ``POST /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
+
+``GET /db/_design/design-doc/_list/list-name/view-name``
+========================================================
+
+.. todo:: GET /db/_design/design-doc/_list/list-name/view-name
+
+* **Method**: ``GET /db/_design/design-doc/_list/list-name/view-name``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
+
+``POST /db/_design/design-doc/_list/list-name/view-name``
+=========================================================
+
+.. todo:: POST /db/_design/design-doc/_list/list-name/view-name
+
+* **Method**: ``POST /db/_design/design-doc/_list/list-name/view-name``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
+
+``PUT /db/_design/design-doc/_update/updatename/doc``
+=====================================================
+
+.. todo:: POST /db/_design/design-doc/_update/updatename/doc
+
+* **Method**: ``POST /db/_design/design-doc/_update/updatename/doc``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
+
+``POST /db/_design/design-doc/_update/updatename``
+==================================================
+
+.. todo:: PUT /db/_design/design-doc/_update/updatename/doc
+
+* **Method**: ``PUT /db/_design/design-doc/_update/updatename/doc``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
+
+``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
+=============================================================
+
+.. todo:: ALL /db/_design/design-doc/_rewrite/rewrite-name/anything
+
+* **Method**: ``ALL /db/_design/design-doc/_rewrite/rewrite-name/anything``
+* **Request**: TBC
+* **Response**: TBC
+* **Admin Privileges Required**: no
http://git-wip-us.apache.org/repos/asf/couchdb/blob/de115c3a/share/doc/src/api/documents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/documents.rst b/share/doc/src/api/documents.rst
new file mode 100644
index 0000000..c58d004
--- /dev/null
+++ b/share/doc/src/api/documents.rst
@@ -0,0 +1,973 @@
+.. 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:
+
+================
+Document Methods
+================
+
+The CouchDB API Server Document methods detail how to create, read,
+update and delete documents within a database.
+
+A list of the available methods and URL paths are provided below:
+
++--------+-------------------------+-------------------------------------------+
+| Method | Path | Description |
++========+=========================+===========================================+
+| POST | /db | Create a new document |
++--------+-------------------------+-------------------------------------------+
+| GET | /db/doc | Returns the latest revision of the |
+| | | document |
++--------+-------------------------+-------------------------------------------+
+| HEAD | /db/doc | Returns bare information in the HTTP |
+| | | Headers for the document |
++--------+-------------------------+-------------------------------------------+
+| PUT | /db/doc | Inserts a new document, or new version |
+| | | of an existing document |
++--------+-------------------------+-------------------------------------------+
+| DELETE | /db/doc | Deletes the document |
++--------+-------------------------+-------------------------------------------+
+| COPY | /db/doc | Copies the document |
++--------+-------------------------+-------------------------------------------+
+| GET | /db/doc/attachment | Gets the attachment of a document |
++--------+-------------------------+-------------------------------------------+
+| PUT | /db/doc/attachment | Adds an attachment of a document |
++--------+-------------------------+-------------------------------------------+
+| DELETE | /db/doc/attachment | Deletes an attachment of a document |
++--------+-------------------------+-------------------------------------------+
+
+``POST /db``
+============
+
+* **Method**: ``POST /db``
+* **Request**: JSON of the new document
+* **Response**: JSON with the committed document information
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: batch
+
+ * **Description**: Allow document store request to be batched with others
+ * **Optional**: yes
+ * **Type**: string
+ * **Supported Values**: asd
+ * **ok**: Enable
+
+* **Return Codes**:
+
+ * **201**:
+ Document has been created successfully
+ * **409**:
+ Conflict - a document with the specified document ID already exists
+
+Create a new document in the specified database, using the supplied JSON
+document structure. If the JSON structure includes the ``_id`` field,
+then the document will be created with the specified document ID. If the
+``_id`` field is not specified, a new unique ID will be generated.
+
+For example, you can generate a new document with a generated UUID using
+the following request:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/recipes/
+ Content-Type: application/json
+
+ {
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh bread",
+ "title" : "Fish Stew"
+ }
+
+The return JSON will specify the automatically generated ID and revision
+information:
+
+.. code-block:: javascript
+
+ {
+ "id" : "64575eef70ab90a2b8d55fc09e00440d",
+ "ok" : true,
+ "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+
+Specifying the Document ID
+--------------------------
+
+The document ID can be specified by including the ``_id`` field in the
+JSON of the submitted record. The following request will create the same
+document with the ID ``FishStew``:
+
+.. code-block:: http
+
+ POST http://couchdb:5984/recipes/
+ Content-Type: application/json
+
+ {
+ "_id" : "FishStew",
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh bread",
+ "title" : "Fish Stew"
+ }
+
+The structure of the submitted document is as shown in the table below:
+
+In either case, the returned JSON will specify the document ID, revision
+ID, and status message:
+
+.. code-block:: javascript
+
+ {
+ "id" : "FishStew",
+ "ok" : true,
+ "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+
+
+.. _api-batch-writes:
+
+UUID generation algorithms
+--------------------------
+
+CouchDB supports a number of different UUID generation algorithms for use
+in situations where a user-specified UUID does not make sense. These
+can be set simply by `PUT http://couchdb:5984/_config/uuids/algorithm`.
+
+
++---------------+---------------------+------------------------------------+
+| Algorithm | Description | Sample UUID |
++===============+=====================+====================================+
+| random | 128 bits of pure | - 43febce5675468a5467fb5467ce9e6c0 |
+| | random awesomeness | |
++---------------+---------------------+------------------------------------+
+| sequential | monotonically | - f755c413badf66b22941313f9f001e28 |
+| | increasing ids with | - f755c413badf66b22941313f9f0024ca |
+| | random increments | - f755c413badf66b22941313f9f00332c |
++---------------+---------------------+------------------------------------+
+| utc_random | time since start of | - 04cfa405381205204f75100d0241ccc3 |
+| | epoch, as 14 hex | - 04cfa4059c48e76e7c054bbe033dd8db |
+| | digits, followed by | - 04cfa405fce10b0df4c08f95e667cd2f |
+| | 18 random digits. | |
++---------------+---------------------+------------------------------------+
+| utc_id | time since start of | - 04cfa718b00848_i_am_in_yer_couch |
+| & additional | epoch, as 14 hex | - 04cfa71d377aef_i_am_in_yer_couch |
+| parameter | digits, followed by | - 04cfa71e0deabd_i_am_in_yer_couch |
+| | utc_id_suffix. | |
++---------------+---------------------+------------------------------------+
+
+.. Impact of UUID choices::
+ The choice of UUID has a signficant impact on the layout of the B-tree,
+ prior to compaction. For example, a sequential UUID algorithm during
+ uploading thousands of documents, will avoid the need to rewrite many
+ intermediate B-tree nodes. A random UUID algorithm may require rewriting
+ intermediate nodes on a regular basis, with a corresponding decrease of
+ throughput, and significant wasted space due to the append-only B-tree
+ design. It is generally recommended to set your own UUIDs, or use the
+ sequential algorithm unless you have a specific need and take into account
+ the likely need for compaction to re-balance the B-tree and reclaim wasted
+ space.
+
+
+Batch Mode Writes
+-----------------
+
+You can write documents to the database at a higher rate by using the
+batch option. This collects document writes together in memory (on a
+user-by-user basis) before they are committed to disk. This increases
+the risk of the documents not being stored in the event of a failure,
+since the documents are not written to disk immediately.
+
+To use the batched mode, append the ``batch=ok`` query argument to the
+URL of the ``PUT`` or ``POST`` request. The CouchDB server will respond
+with a 202 HTTP response code immediately.
+
+Including Attachments
+---------------------
+
+You can include one or more attachments with a given document by
+incorporating the attachment information within the JSON of the
+document. This provides a simpler alternative to loading documents with
+attachments than making a separate call (see :ref:`api-put-attachment`).
+
+* **_id** (optional): Document ID
+* **_rev** (optional): Revision ID (when updating an existing document)
+* **_attachments** (optional): Document Attachment
+
+ * **filename**: Attachment information
+
+ * **content_type**: MIME Content type string
+ * **data**: File attachment content, Base64 encoded
+
+The ``filename`` will be the attachment name. For example, when sending
+the JSON structure below:
+
+.. code-block:: javascript
+
+ {
+ "_id" : "FishStew",
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh bread",
+ "title" : "Fish Stew"
+ "_attachments" : {
+ "styling.css" : {
+ "content-type" : "text/css",
+ "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
+ },
+ },
+ }
+
+
+The attachment ``styling.css`` can be accessed using
+``/recipes/FishStew/styling.css``. For more information on attachments,
+see :ref:`api-get-attachment`.
+
+The document data embedded in to the structure must be encoded using
+base64.
+
+.. _api-get-doc:
+
+``GET /db/doc``
+===============
+
+* **Method**: ``GET /db/doc``
+* **Request**: None
+* **Response**: Returns the JSON for the document
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: conflicts
+
+ * **Description**: Returns the conflict tree for the document.
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Default**: false
+ * **Supported Values**:
+
+ * **true**: Includes the revisions
+
+ * **Argument**: rev
+
+ * **Description**: Specify the revision to return
+ * **Optional**: yes
+ * **Type**: string
+ * **Supported Values**:
+
+ * **true**: Includes the revisions
+
+ * **Argument**: revs
+
+ * **Description**: Return a list of the revisions for the document
+ * **Optional**: yes
+ * **Type**: boolean
+
+ * **Argument**: revs_info
+
+ * **Description**: Return a list of detailed revision information for the
+ document
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Supported Values**:
+
+ * **true**: Includes the revisions
+
+* **Return Codes**:
+
+ * **200**:
+ Document retrieved
+ * **400**:
+ The format of the request or revision was invalid
+ * **404**:
+ The specified document or revision cannot be found, or has been deleted
+ * **409**:
+ Conflict - a document with the specified document ID already exists
+
+Returns the specified ``doc`` from the specified ``db``. For example, to
+retrieve the document with the id ``FishStew`` you would send the
+following request:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/FishStew
+ Content-Type: application/json
+ Accept: application/json
+
+The returned JSON is the JSON of the document, including the document ID
+and revision number:
+
+.. code-block:: javascript
+
+ {
+ "_id" : "FishStew",
+ "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c",
+ "servings" : 4,
+ "subtitle" : "Delicious with a green salad",
+ "title" : "Irish Fish Stew"
+ }
+
+
+Unless you request a specific revision, the latest revision of the
+document will always be returned.
+
+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. For example:
+
+.. code-block:: javascript
+
+ {
+ "_id" : "FishStew",
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh bread",
+ "title" : "Fish Stew"
+ "_attachments" : {
+ "styling.css" : {
+ "stub" : true,
+ "content-type" : "text/css",
+ "length" : 783426,
+ },
+ },
+ }
+
+The format of the returned JSON is shown in the table below:
+
+* **_id** (optional): Document ID
+* **_rev** (optional): Revision ID (when updating an existing document)
+* **_attachments** (optional): Document Attachment
+
+ * **filename**: Attachment information
+
+ * **content_type**: MIME Content type string
+ * **length**: Length (bytes) of the attachment data
+ * **revpos**: Revision where this attachment exists
+ * **stub**: Indicates whether the attachment is a stub
+
+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. For example:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/FishStew?revs=true
+ Accept: application/json
+
+The returned JSON structure includes the original document, including a
+``_revisions`` structure that includes the revision information:
+
+.. code-block:: javascript
+
+ {
+ "servings" : 4,
+ "subtitle" : "Delicious with a green salad",
+ "_id" : "FishStew",
+ "title" : "Irish Fish Stew",
+ "_revisions" : {
+ "ids" : [
+ "a1a9b39ee3cc39181b796a69cb48521c",
+ "7c4740b4dcf26683e941d6641c00c39d",
+ "9c65296036141e575d32ba9c034dd3ee"
+ ],
+ "start" : 3
+ },
+ "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ }
+
+* **_id** (optional): Document ID
+* **_rev** (optional): Revision ID (when updating an existing document)
+* **_revisions**: CouchDB Document Revisions
+
+ * **ids** [array]: Array of valid revision IDs, in reverse order
+ (latest first)
+ * **start**: Prefix number for the latest revision
+
+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:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/FishStew?revs_info=true
+ Accept: application/json
+
+This returns extended revision information, including the availability
+and status of each revision:
+
+.. code-block:: javascript
+
+ {
+ "servings" : 4,
+ "subtitle" : "Delicious with a green salad",
+ "_id" : "FishStew",
+ "_revs_info" : [
+ {
+ "status" : "available",
+ "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ },
+ {
+ "status" : "available",
+ "rev" : "2-7c4740b4dcf26683e941d6641c00c39d"
+ },
+ {
+ "status" : "available",
+ "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+ ],
+ "title" : "Irish Fish Stew",
+ "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+ }
+
+* **_id** (optional): Document ID
+* **_rev** (optional): Revision ID (when updating an existing document)
+* **_revs_info** [array]: CouchDB Document Extended Revision Info
+
+ * **rev**: Full revision string
+ * **status**: Status of the revision
+
+Obtaining a Specific Revision
+-----------------------------
+
+To get a specific revision, use the ``rev`` argument to the request, and
+specify the full revision number:
+
+.. code-block:: http
+
+ GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d
+ Accept: application/json
+
+The specified revision of the document will be returned, including a
+``_rev`` field specifying the revision that was requested:
+
+.. code-block:: javascript
+
+ {
+ "_id" : "FishStew",
+ "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
+ "servings" : 4,
+ "subtitle" : "Delicious with a green salad",
+ "title" : "Fish Stew"
+ }
+
+``HEAD /db/doc``
+================
+
+* **Method**: ``HEAD /db/doc``
+* **Request**: None
+* **Response**: None
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Specify the revision to return
+ * **Optional**: yes
+ * **Type**: string
+
+ * **Argument**: revs
+
+ * **Description**: Return a list of the revisions for the document
+ * **Optional**: yes
+ * **Type**: boolean
+
+ * **Argument**: revs_info
+
+ * **Description**: Return a list of detailed revision information for the
+ document
+ * **Optional**: yes
+ * **Type**: boolean
+
+* **Return Codes**:
+
+ * **404**:
+ The specified document or revision cannot be found, or has been deleted
+
+Returns the HTTP Headers containing a minimal amount of information
+about the specified document. The method supports the same query
+arguments as the ``GET`` method, but only the header information
+(including document size, and the revision as an ETag), is returned. For
+example, a simple ``HEAD`` request:
+
+.. code-block:: http
+
+ HEAD http://couchdb:5984/recipes/FishStew
+ Content-Type: application/json
+
+
+Returns the following HTTP Headers:
+
+.. code-block:: javascript
+
+ HTTP/1.1 200 OK
+ Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+ Etag: "7-a19a1a5ecd946dad70e85233ba039ab2"
+ Date: Fri, 05 Nov 2010 14:54:43 GMT
+ Content-Type: text/plain;charset=utf-8
+ Content-Length: 136
+ Cache-Control: must-revalidate
+
+The ``Etag`` header shows the current revision for the requested
+document, and the ``Content-Length`` specifies the length of the data,
+if the document were requested in full.
+
+Adding any of the query arguments (as supported by ```GET```_ method),
+then the resulting HTTP Headers will correspond to what would be
+returned. Note that the current revision is not returned when the
+``refs_info`` argument is used. For example:
+
+.. code-block:: http
+
+ HTTP/1.1 200 OK
+ Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+ Date: Fri, 05 Nov 2010 14:57:16 GMT
+ Content-Type: text/plain;charset=utf-8
+ Content-Length: 609
+ Cache-Control: must-revalidate
+
+.. _api-put-doc:
+
+``PUT /db/doc``
+===============
+
+* **Method**: ``PUT /db/doc``
+* **Request**: JSON of the new document, or updated version of the existed
+ document
+* **Response**: JSON of the document ID and revision
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: batch
+
+ * **Description**: Allow document store request to be batched with others
+ * **Optional**: yes
+ * **Type**: string
+ * **Supported Values**:
+
+ * **ok**: Enable
+
+* **HTTP Headers**
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **201**:
+ Document has been created successfully
+ * **202**:
+ Document accepted for writing (batch mode)
+
+
+The ``PUT`` method creates a new named document, or creates a new
+revision of the existing document. Unlike the ``POST`` method, you
+must specify the document ID in the request URL.
+
+For example, to create the document ``FishStew``, you would send the
+following request:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/FishStew
+ Content-Type: application/json
+
+ {
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh bread",
+ "title" : "Fish Stew"
+ }
+
+The return type is JSON of the status, document ID,and revision number:
+
+.. code-block:: javascript
+
+ {
+ "id" : "FishStew",
+ "ok" : true,
+ "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+
+Updating an Existing Document
+-----------------------------
+
+To update an existing document you must specify the current revision
+number within the ``_rev`` parameter. For example:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/FishStew
+ Content-Type: application/json
+
+ {
+ "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh salad",
+ "title" : "Fish Stew"
+ }
+
+Alternatively, you can supply the current revision number in the
+``If-Match`` HTTP header of the request. For example:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/FishStew
+ If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea
+ Content-Type: application/json
+
+ {
+ "servings" : 4,
+ "subtitle" : "Delicious with fresh salad",
+ "title" : "Fish Stew"
+ }
+
+The JSON returned will include the updated revision number:
+
+.. code-block:: javascript
+
+ {
+ "id" : "FishStew99",
+ "ok" : true,
+ "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
+ }
+
+For information on batched writes, which can provide improved
+performance, see :ref:`api-batch-writes`.
+
+.. _api-del-doc:
+
+``DELETE /db/doc``
+==================
+
+* **Method**: ``DELETE /db/doc``
+* **Request**: None
+* **Response**: JSON of the deleted revision
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **409**:
+ Revision is missing, invalid or not the latest
+
+Deletes the specified document from the database. You must supply the
+current (latest) revision, either by using the ``rev`` parameter to
+specify the revision:
+
+.. code-block:: http
+
+ DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
+ Content-Type: application/json
+
+Alternatively, you can use ETags with the ``If-Match`` field:
+
+.. code-block:: http
+
+ DELETE http://couchdb:5984/recipes/FishStew
+ If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
+ Content-Type: application/json
+
+
+The returned JSON contains the document ID, revision and status:
+
+.. code-block:: javascript
+
+ {
+ "id" : "FishStew",
+ "ok" : true,
+ "rev" : "4-2719fd41187c60762ff584761b714cfb"
+ }
+
+.. note:: Note that deletion of a record increments the revision number. The
+ use of a revision for deletion of the record allows replication of
+ the database to correctly track the deletion in synchronized copies.
+
+.. _api-copy-doc:
+
+``COPY /db/doc``
+================
+
+* **Method**: ``COPY /db/doc``
+* **Request**: None
+* **Response**: JSON of the new document and revision
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Revision to copy from
+ * **Optional**: yes
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``Destination``
+
+ * **Description**: Destination document (and optional revision)
+ * **Optional**: no
+
+* **Return Codes**:
+
+ * **201**:
+ Document has been copied and created successfully
+ * **409**:
+ Revision is missing, invalid or not the latest
+
+The ``COPY`` command (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
+``Destination`` HTTP Header of the request specifying the target
+document.
+
+Copying a Document
+------------------
+
+You can copy the latest version of a document to a new document by
+specifying the current document and target document:
+
+.. code-block:: http
+
+ COPY http://couchdb:5984/recipes/FishStew
+ Content-Type: application/json
+ Destination: IrishFishStew
+
+The above request copies the document ``FishStew`` to the new document
+``IrishFishStew``. The response is the ID and revision of the new
+document.
+
+.. code-block:: javascript
+
+ {
+ "id" : "IrishFishStew",
+ "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+
+Copying from a Specific Revision
+--------------------------------
+
+To copy *from* a specific version, use the ``rev`` argument to the query
+string:
+
+.. code-block:: http
+
+ COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082
+ Content-Type: application/json
+ Destination: IrishFishStew
+
+The new document will be created using the information in the specified
+revision of the source document.
+
+Copying to an Existing Document
+-------------------------------
+
+To copy to an existing document, you must specify the current revision
+string for the target document, using the ``rev`` parameter to the
+``Destination`` HTTP Header string. For example:
+
+.. code-block:: http
+
+ COPY http://couchdb:5984/recipes/FishStew
+ Content-Type: application/json
+ Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee
+
+The return value will be the new revision of the copied document:
+
+.. code-block:: javascript
+
+ {
+ "id" : "IrishFishStew",
+ "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
+ }
+
+.. _api-get-attachment:
+
+``GET /db/doc/attachment``
+==========================
+
+* **Method**: ``GET /db/doc/attachment``
+* **Request**: None
+* **Response**: Returns the attachment data
+* **Admin Privileges Required**: no
+
+Returns the file attachment ``attachment`` associated with the document
+``doc``. The raw data of the associated attachment is returned (just as
+if you were accessing a static file. The returned HTTP ``Content-type``
+will be the same as the content type set when the document attachment
+was submitted into the database.
+
+.. _api-put-attachment:
+
+``PUT /db/doc/attachment``
+==========================
+
+* **Method**: ``PUT /db/doc/attachment``
+* **Request**: Raw document data
+* **Response**: JSON document status
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current document revision
+ * **Optional**: no
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``Content-Length``
+
+ * **Description**: Length (bytes) of the attachment being uploaded
+ * **Optional**: no
+
+ * **Header**: ``Content-Type``
+
+ * **Description**: MIME type for the uploaded attachment
+ * **Optional**: no
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **201**:
+ Attachment has been accepted
+
+Upload the supplied content as an attachment to the specified document
+(``doc``). The ``attachment`` name provided must be a URL encoded
+string. You must also supply either the ``rev`` query argument or the
+``If-Match`` HTTP header for validation, and the HTTP headers (to set
+the attachment content type). The content type is used when the
+attachment is requested as the corresponding content-type in the
+returned document header.
+
+For example, you could upload a simple text document using the following
+request:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca
+ Content-Length: 10
+ Content-Type: text/plain
+
+ Roast it
+
+Or by using the ``If-Match`` HTTP header:
+
+.. code-block:: http
+
+ PUT http://couchdb:5984/recipes/FishStew/basic
+ If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca
+ Content-Length: 10
+ Content-Type: text/plain
+
+ Roast it
+
+The returned JSON contains the new document information:
+
+.. code-block:: javascript
+
+ {
+ "id" : "FishStew",
+ "ok" : true,
+ "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
+ }
+
+.. note:: Uploading an attachment updates the corresponding document revision.
+ Revisions are tracked for the parent document, not individual
+ attachments.
+
+Updating an Existing Attachment
+-------------------------------
+
+Uploading an attachment using an existing attachment name will update
+the corresponding stored content of the database. Since you must supply
+the revision information to add an attachment to a document, this serves
+as validation to update the existing attachment.
+
+``DELETE /db/doc/attachment``
+=============================
+
+* **Method**: ``DELETE /db/doc/attachment``
+* **Request**: None
+* **Response**: JSON status
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current document revision
+ * **Optional**: no
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **200**:
+ Attachment deleted successfully
+ * **409**:
+ Supplied revision is incorrect or missing
+
+Deletes the attachment ``attachment`` to the specified ``doc``. You must
+supply the ``rev`` argument with the current revision to delete the
+attachment.
+
+For example to delete the attachment ``basic`` from the recipe
+``FishStew``:
+
+.. code-block:: http
+
+ DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
+ Content-Type: application/json
+
+
+
+The returned JSON contains the updated revision information:
+
+.. code-block:: javascript
+
+ {
+ "id" : "FishStew",
+ "ok" : true,
+ "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
+ }
+
+.. _JSON object: #table-couchdb-api-db_db-json-changes
+.. _POST: #couchdb-api-dbdoc_db_post
http://git-wip-us.apache.org/repos/asf/couchdb/blob/de115c3a/share/doc/src/api/local.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/local.rst b/share/doc/src/api/local.rst
new file mode 100644
index 0000000..780c030
--- /dev/null
+++ b/share/doc/src/api/local.rst
@@ -0,0 +1,169 @@
+.. 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) Document Methods
+========================================
+
+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 ``_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/local-doc | Returns the latest revision of the |
+| | | non-replicated document |
++--------+-------------------------+-------------------------------------------+
+| PUT | /db/_local/local-doc | Inserts a new version of the |
+| | | non-replicated document |
++--------+-------------------------+-------------------------------------------+
+| DELETE | /db/_local/local-doc | Deletes the non-replicated document |
++--------+-------------------------+-------------------------------------------+
+| COPY | /db/_local/local-doc | Copies the non-replicated document |
++--------+-------------------------+-------------------------------------------+
+
+``GET /db/_local/local-doc``
+============================
+
+* **Method**: ``GET /db/_local/local-doc``
+* **Request**: None
+* **Response**: JSON of the returned document
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Specify the revision to return
+ * **Optional**: yes
+ * **Type**: string
+ * **Supported Values**:
+
+ * **true**: Includes the revisions
+
+ * **Argument**: revs
+
+ * **Description**: Return a list of the revisions for the document
+ * **Optional**: yes
+ * **Type**: boolean
+
+ * **Argument**: revs_info
+
+ * **Description**: Return a list of detailed revision information for
+ the document
+ * **Optional**: yes
+ * **Type**: boolean
+ * **Supported Values**
+
+ * **true**: Includes the revisions
+
+* **Return Codes**:
+
+ * **400**:
+ The format of the request or revision was invalid
+ * **404**:
+ The specified document or revision cannot be found, or has been deleted
+
+Gets the specified local document. The semantics are identical to
+accessing a standard document in the specified database, except that the
+document is not replicated. See :ref:`api-get-doc`.
+
+``PUT /db/_local/local-doc``
+============================
+
+* **Method**: ``PUT /db/_local/local-doc``
+* **Request**: JSON of the document
+* **Response**: JSON with the committed document information
+* **Admin Privileges Required**: no
+* **Return Codes**:
+
+ * **201**:
+ Document has been created successfully
+
+Stores the specified local document. The semantics are identical to
+storing a standard document in the specified database, except that the
+document is not replicated. See :ref:`api-put-doc`.
+
+``DELETE /db/_local/local-doc``
+===============================
+
+* **Method**: ``DELETE /db/_local/local-doc``
+* **Request**: None
+* **Response**: JSON with the deleted document information
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``If-Match``
+
+ * **Description**: Current revision of the document for validation
+ * **Optional**: yes
+
+* **Return Codes**:
+
+ * **409**:
+ Supplied revision is incorrect or missing
+
+Deletes the specified local document. The semantics are identical to
+deleting a standard document in the specified database, except that the
+document is not replicated. See :ref:`api-del-doc`.
+
+``COPY /db/_local/local-doc``
+=============================
+
+* **Method**: ``COPY /db/_local/local-doc``
+* **Request**: None
+* **Response**: JSON of the copied document
+* **Admin Privileges Required**: no
+* **Query Arguments**:
+
+ * **Argument**: rev
+
+ * **Description**: Revision to copy from
+ * **Optional**: yes
+ * **Type**: string
+
+* **HTTP Headers**
+
+ * **Header**: ``Destination``
+
+ * **Description**: Destination document (and optional revision)
+ * **Optional**: no
+
+Copies the specified local document. The semantics are identical to
+copying a standard document in the specified database, except that the
+document is not replicated. See :ref:`api-copy-doc`.