.. 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