couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [36/49] export DocBook XML to RST files
Date Fri, 14 Sep 2012 10:17:00 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/5cb488bf/share/docs/rst/manual.rst
----------------------------------------------------------------------
diff --git a/share/docs/rst/manual.rst b/share/docs/rst/manual.rst
new file mode 100644
index 0000000..7c56f12
--- /dev/null
+++ b/share/docs/rst/manual.rst
@@ -0,0 +1,19092 @@
+====================================
+CouchDB \_\_meta\_version\_\_ Manual
+====================================
+
+CouchDB API Server Authentication Methods
+=========================================
+
+The CouchDB Authentication methods provide an interface for obtaining
+session and authorization data.
+
+A list of the available methods and URL paths are provided below:
+
+Authentication API Calls
+
+CouchDB API Server Configuration Methods
+========================================
+
+The CouchDB API Server Configuration Methods provide an interface to
+query and update the various configuration values within a running
+CouchDB instance.
+
+A list of the available methods and URL paths are provided below:
+
+Configuration API Calls
+
+``GET /_config``
+================
+
+Returns the entire CouchDB server configuration as a JSON structure. The
+structure is organized by different configuration sections, with
+individual values.
+
+For example, to get the configuration for a server:
+
+::
+
+    GET http://couchdb:5984/_config
+    Accept: application/json
+
+The response is the JSON structure:
+
+::
+
+    {
+       "query_server_config" : {
+          "reduce_limit" : "true"
+       },
+       "couchdb" : {
+          "os_process_timeout" : "5000",
+          "max_attachment_chunk_size" : "4294967296",
+          "max_document_size" : "4294967296",
+          "uri_file" : "/var/lib/couchdb/couch.uri",
+          "max_dbs_open" : "100",
+          "view_index_dir" : "/var/lib/couchdb",
+          "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib",
+          "database_dir" : "/var/lib/couchdb",
+          "delayed_commits" : "true"
+       },
+       "attachments" : {
+          "compressible_types" : "text/*, application/javascript, application/json,  application/xml",
+          "compression_level" : "8"
+       },
+       "uuids" : {
+          "algorithm" : "utc_random"
+       },
+       "daemons" : {
+          "view_manager" : "{couch_view, start_link, []}",
+          "auth_cache" : "{couch_auth_cache, start_link, []}",
+          "uuids" : "{couch_uuids, start, []}",
+          "stats_aggregator" : "{couch_stats_aggregator, start, []}",
+          "query_servers" : "{couch_query_servers, start_link, []}",
+          "httpd" : "{couch_httpd, start_link, []}",
+          "stats_collector" : "{couch_stats_collector, start, []}",
+          "db_update_notifier" : "{couch_db_update_notifier_sup, start_link, []}",
+          "external_manager" : "{couch_external_manager, start_link, []}"
+       },
+       "stats" : {
+          "samples" : "[0, 60, 300, 900]",
+          "rate" : "1000"
+       },
+       "httpd" : {
+          "vhost_global_handlers" : "_utils, _uuids, _session, _oauth, _users",
+          "secure_rewrites" : "true",
+          "authentication_handlers" : "{couch_httpd_oauth, oauth_authentication_handler},
+                                       {couch_httpd_auth, cookie_authentication_handler},
+                                       {couch_httpd_auth, default_authentication_handler}",
+          "port" : "5984",
+          "default_handler" : "{couch_httpd_db, handle_request}",
+          "allow_jsonp" : "false",
+          "bind_address" : "192.168.0.2",
+          "max_connections" : "2048"
+       },
+       "query_servers" : {
+          "javascript" : "/usr/bin/couchjs /usr/share/couchdb/server/main.js"
+       },
+       "couch_httpd_auth" : {
+          "authentication_db" : "_users",
+          "require_valid_user" : "false",
+          "authentication_redirect" : "/_utils/session.html",
+          "timeout" : "600",
+          "auth_cache_size" : "50"
+       },
+       "httpd_db_handlers" : {
+          "_design" : "{couch_httpd_db, handle_design_req}",
+          "_compact" : "{couch_httpd_db, handle_compact_req}",
+          "_view_cleanup" : "{couch_httpd_db, handle_view_cleanup_req}",
+          "_temp_view" : "{couch_httpd_view, handle_temp_view_req}",
+          "_changes" : "{couch_httpd_db, handle_changes_req}"
+       },
+       "replicator" : {
+          "max_http_sessions" : "10",
+          "max_http_pipeline_size" : "10"
+       },
+       "log" : {
+          "include_sasl" : "true",
+          "level" : "info",
+          "file" : "/var/log/couchdb/couch.log"
+       },
+       "httpd_design_handlers" : {
+          "_update" : "{couch_httpd_show, handle_doc_update_req}",
+          "_show" : "{couch_httpd_show, handle_doc_show_req}",
+          "_info" : "{couch_httpd_db,   handle_design_info_req}",
+          "_list" : "{couch_httpd_show, handle_view_list_req}",
+          "_view" : "{couch_httpd_view, handle_view_req}",
+          "_rewrite" : "{couch_httpd_rewrite, handle_rewrite_req}"
+       },
+       "httpd_global_handlers" : {
+          "_replicate" : "{couch_httpd_misc_handlers, handle_replicate_req}",
+          "/" : "{couch_httpd_misc_handlers, handle_welcome_req, <<\"Welcome\">>}",
+          "_config" : "{couch_httpd_misc_handlers, handle_config_req}",
+          "_utils" : "{couch_httpd_misc_handlers, handle_utils_dir_req, \"/usr/share/couchdb/www\"}",
+          "_active_tasks" : "{couch_httpd_misc_handlers, handle_task_status_req}",
+          "_session" : "{couch_httpd_auth, handle_session_req}",
+          "_log" : "{couch_httpd_misc_handlers, handle_log_req}",
+          "favicon.ico" : "{couch_httpd_misc_handlers, handle_favicon_req, \"/usr/share/couchdb/www\"}",
+          "_all_dbs" : "{couch_httpd_misc_handlers, handle_all_dbs_req}",
+          "_oauth" : "{couch_httpd_oauth, handle_oauth_req}",
+          "_restart" : "{couch_httpd_misc_handlers, handle_restart_req}",
+          "_uuids" : "{couch_httpd_misc_handlers, handle_uuids_req}",
+          "_stats" : "{couch_httpd_stats_handlers, handle_stats_req}"
+       }
+    }
+        
+
+``GET /_config/section``
+========================
+
+Gets the configuration structure for a single section. For example, to
+retrieve the CouchDB configuration section values:
+
+::
+
+    GET http://couchdb:5984/_config/couchdb
+    Accept: application/json
+
+The returned JSON contains just the configuration values for this
+section:
+
+::
+
+    {
+       "os_process_timeout" : "5000",
+       "max_attachment_chunk_size" : "4294967296",
+       "max_document_size" : "4294967296",
+       "uri_file" : "/var/lib/couchdb/couch.uri",
+       "max_dbs_open" : "100",
+       "view_index_dir" : "/var/lib/couchdb",
+       "util_driver_dir" : "/usr/lib64/couchdb/erlang/lib/couch-1.0.1/priv/lib",
+       "database_dir" : "/var/lib/couchdb",
+       "delayed_commits" : "true"
+    }
+
+``GET /_config/section/key``
+============================
+
+Gets a single configuration value from within a specific configuration
+section. For example, to obtain the current log level:
+
+::
+
+    GET http://couchdb:5984/_config/log/level
+    Accept: application/json
+
+Returns the string of the log level:
+
+::
+
+    "info"
+
+    **Note**
+
+    The returned value will be the JSON of the value, which may be a
+    string or numeric value, or an array or object. Some client
+    environments may not parse simple strings or numeric values as valid
+    JSON.
+
+``PUT /_config/section/key``
+============================
+
+Updates a configuration value. The new value should be supplied in the
+request body in the corresponding JSON format. For example, if you are
+setting a string value, you must supply a valid JSON string.
+
+For example, to set the function used to generate UUIDs by the
+``GET /_uuids`` API call to use the ``utc_random`` generator:
+
+::
+
+    PUT http://couchdb:5984/_config/uuids/algorithm
+    Content-Type: application/json
+
+    "utc_random"
+
+The return value will be empty, with the response code indicating the
+success or failure of the configuration setting.
+
+``DELETE /_config/section/key``
+===============================
+
+Deletes a configuration value. The returned JSON will be the value of
+the configuration parameter before it was deleted. For example, to
+delete the UUID parameter:
+
+::
+
+    DELETE http://couchdb:5984/_config/uuids/algorithm
+    Content-Type: application/json
+
+The returned value is the last configured UUID function:
+
+::
+
+    "random"
+
+CouchDB API Server Database Methods
+===================================
+
+The Database methods provide an interface to an entire database withing
+CouchDB. These are database, rather than document, level requests.
+
+A list of the available methods and URL paths are provided below:
+
+Database API Calls
+
+For all the database methods, the database name within the URL path
+should be the database name that you wish to perform the operation on.
+For example, to obtain the meta information for the database
+``recipes``, you would use the HTTP request:
+
+::
+
+    GET /recipes
+
+For clarity, the form below is used in the URL paths:
+
+::
+
+    GET /db
+
+Where ``db`` is the name of any database.
+
+``GET /db``
+===========
+
+Gets information about the specified database. For example, to retrieve
+the information for the database ``recipe``:
+
+::
+
+    GET http://couchdb:5984/recipes
+    Accept: application/json
+
+The JSON response contains meta information about the database. A sample
+of the JSON returned for an empty database is provided below:
+
+::
+
+    {
+       "compact_running" : false,
+       "committed_update_seq" : 375048,
+       "disk_format_version" : 5,
+       "disk_size" : 33153123,
+       "doc_count" : 18386,
+       "doc_del_count" : 0,
+       "db_name" : "recipes",
+       "instance_start_time" : "1290700340925570",
+       "purge_seq" : 10,
+       "update_seq" : 375048
+    }
+        
+
+The elements of the returned structure are shown in the table below:
+
+``PUT /db``
+===========
+
+Creates a new database. The database name must be composed of one or
+more of the following characters:
+
+-  Lowercase characters (``a-z``)
+
+-  Name must begin with a lowercase letter
+
+-  Digits (``0-9``)
+
+-  Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and
+   ``/``.
+
+Trying to create a database that does not meet these requirements will
+return an error quoting these restrictions.
+
+To create the database ``recipes``:
+
+::
+
+    PUT http://couchdb:5984/recipes
+    Content-Type: application/json
+
+The returned content contains the JSON status:
+
+::
+
+    {
+       "ok" : true
+    }
+
+Anything should be treated as an error, and the problem should be taken
+form the HTTP response code.
+
+``DELETE /db``
+==============
+
+Deletes the specified database, and all the documents and attachments
+contained within it.
+
+To delete the database ``recipes`` you would send the request:
+
+::
+
+    DELETE http://couchdb:5984/recipes
+    Content-Type: application/json
+
+If successful, the returned JSON will indicate success
+
+::
+
+    {
+       "ok" : true
+    }
+
+``GET /db/_changes``
+====================
+
+Obtains a list of the changes made to the database. This can be used to
+monitor for update and modifications to the database for post processing
+or synchronization. There are three different types of supported changes
+feeds, poll, longpoll, and continuous. All requests are poll requests by
+default. You can select any feed type explicitly using the ``feed``
+query argument.
+
+-  **Poll**
+
+   With polling you can request the changes that have occured since a
+   specific sequence number. This returns the JSON structure containing
+   the changed document information. When you perform a poll change
+   request, only the changes since the specific sequence number are
+   returned. For example, the query
+
+   ::
+
+       DELETE http://couchdb:5984/recipes/_changes
+       Content-Type: application/json
+
+   Will get all of the changes in the database. You can request a
+   starting point using the ``since`` query argument and specifying the
+   sequence number. You will need to record the latest sequence number
+   in your client and then use this when making another request as the
+   new value to the ``since`` parameter.
+
+-  **Longpoll**
+
+   With long polling the request to the server will remain open until a
+   change is made on the database, when the changes will be reported,
+   and then the connection will close. The long poll is useful when you
+   want to monitor for changes for a specific purpose without wanting to
+   monitoring continuously for changes.
+
+   Because the wait for a change can be significant you can set a
+   timeout before the connection is automatically closed (the
+   ``timeout`` argument). You can also set a heartbeat interval (using
+   the ``heartbeat`` query argument), which sends a newline to keep the
+   connection open.
+
+-  **Continuous**
+
+   Continuous sends all new changes back to the client immediately,
+   without closing the connection. In continuous mode the format of the
+   changes is slightly different to accommodate the continuous nature
+   while ensuring that the JSON output is still valid for each change
+   notification.
+
+   As with the longpoll feed type you can set both the timeout and
+   heartbeat intervals to ensure that the connection is kept open for
+   new changesand updates.
+
+The return structure for ``normal`` and ``longpoll`` modes is a JSON
+array of changes objects, and the last update sequence number. The
+structure is described in the following table.
+
+The return format for ``continuous`` mode the server sends a CRLF
+(carriage-return, linefeed) delimited line for each change. Each line
+contains the `JSON object`_.
+
+You can also request the full contents of each document change (instead
+of just the change notification) by using the ``include_docs``
+parameter.
+
+Filtering
+---------
+
+You can filter the contents of the changes feed in a number of ways. The
+most basic way is to specify one or more document IDs to the query. This
+causes the returned structure value to only contain changes for the
+specified IDs. Note that the value of this query argument should be a
+JSON formatted array.
+
+You can also filter the ``_changes`` feed by defining a filter function
+within a design document. The specification for the filter is the same
+as for replication filters. You specify the name of the filter function
+to the ``filter`` parameter, specifying the design document name and
+filter name. For example:
+
+::
+
+    GET /db/_changes?filter=design_doc/filtername
+
+The ``_changes`` feed can be used to watch changes to specific document
+ID's or the list of ``_design`` documents in a database. If the
+``filters`` parameter is set to ``_doc_ids`` a list of doc IDs can be
+passed in the ``doc_ids`` parameter as a JSON array.
+
+For more information, see ?.
+
+``POST /db/_compact``
+=====================
+
+Request compaction of the specified database. Compaction compresses the
+disk database file by performing the following operations:
+
+-  Writes a new version of the database file, removing any unused
+   sections from the new version during write. Because a new file is
+   temporary created for this purpose, you will need twice the current
+   storage space of the specified database in order for the compaction
+   routine to complete.
+
+-  Removes old revisions of documents from the database, up to the
+   per-database limit specified by the ``_revs_limit`` database
+   parameter. See ? .
+
+Compaction can only be requested on an individual database; you cannot
+compact all the databases for a CouchDB instance. The compaction process
+runs as a background process.
+
+You can determine if the compaction process is operating on a database
+by obtaining the database meta information, the ``compact_running``
+value of the returned database structure will be set to true. See ? .
+
+You can also obtain a list of running processes to determine whether
+compaction is currently running. See ?.
+
+``POST /db/_compact/design-doc``
+================================
+
+Compacts the view indexes associated with the specified design document.
+You can use this in place of the full database compaction if you know a
+specific set of view indexes have been affected by a recent database
+change.
+
+For example, to compact the views associated with the ``recipes`` design
+document:
+
+::
+
+    POST http://couchdb:5984/recipes/_compact/recipes
+    Content-Type: application/json
+
+CouchDB will immediately return with a status indicating that the
+compaction request has been received (HTTP status code 202):
+
+::
+
+    {
+       "ok" : true
+    }
+        
+
+``POST /db/_view_cleanup``
+==========================
+
+Cleans up the cached view output on disk for a given view. For example:
+
+::
+
+    POST http://couchdb:5984/recipes/_view_cleanup
+    Content-Type: application/json
+
+If the request is successful, a basic status message us returned:
+
+::
+
+    {
+       "ok" : true
+    }
+        
+
+``POST /db/_ensure_full_commit``
+================================
+
+Commits any recent changes to the specified database to disk. You should
+call this if you want to ensure that recent changes have been written.
+For example, to commit all the changes to disk for the database
+``recipes`` you would use:
+
+::
+
+    POST http://couchdb:5984/recipes/_ensure_full_commit
+    Content-Type: application/json
+
+This returns a status message, containing the success message and the
+timestamp for when the CouchDB instance was started:
+
+::
+
+    {
+      "ok" : true,
+      "instance_start_time" : "1288186189373361"
+    }
+
+``POST /db/_bulk_docs``
+=======================
+
+The bulk document API allows you to create and update multiple documents
+at the same time within a single request. The basic operation is similar
+to creating or updating a single document, except that you batch the
+document structure and information and . When creating new documents the
+document ID is optional. For updating existing documents, you must
+provide the document ID, revision information, and new document values.
+
+For both inserts and updates the basic structure of the JSON is the
+same:
+
+Inserting Documents in Bulk
+---------------------------
+
+To insert documents in bulk into a database you need to supply a JSON
+structure with the array of documents that you want to add to the
+database. Using this method you can either include a document ID, or
+allow the document ID to be automatically generated.
+
+For example, the following inserts three new documents, two with the
+supplied document IDs, and one which will have a document ID generated:
+
+::
+
+    {
+       "docs" : [
+          {
+             "_id" : "FishStew",
+             "servings" : 4,
+             "subtitle" : "Delicious with fresh bread",
+             "title" : "Fish Stew"
+          },
+          {
+             "_id" : "LambStew",
+             "servings" : 6,
+             "subtitle" : "Delicious with scone topping",
+             "title" : "Lamb Stew"
+          },
+          {
+             "servings" : 8,
+             "subtitle" : "Delicious with suet dumplings",
+             "title" : "Beef Stew"
+          },
+       ]
+    }
+          
+
+The return type from a bulk insertion will be 201, with the content of
+the returned structure indicating specific success or otherwise messages
+on a per-document basis.
+
+The return structure from the example above contains a list of the
+documents created, here with the combination and their revision IDs:
+
+::
+
+    POST http://couchdb:5984/recipes/_bulk_docs
+    Content-Type: application/json
+
+    [
+       {
+          "id" : "FishStew",
+          "rev" : "1-9c65296036141e575d32ba9c034dd3ee",
+       },
+       {
+          "id" : "LambStew",
+          "rev" : "1-34c318924a8f327223eed702ddfdc66d",
+       },
+       {
+          "id" : "7f7638c86173eb440b8890839ff35433",
+          "rev" : "1-857c7cbeb6c8dd1dd34a0c73e8da3c44",
+       }
+    ]
+              
+
+The content and structure of the returned JSON will depend on the
+transaction semantics being used for the bulk update; see ? for more
+information. Conflicts and validation errors when updating documents in
+bulk must be handled separately; see ?.
+
+Updating Documents in Bulk
+--------------------------
+
+The bulk document update procedure is similar to the insertion
+procedure, except that you must specify the document ID and current
+revision for every document in the bulk update JSON string.
+
+For example, you could send the following request:
+
+::
+
+    POST http://couchdb:5984/recipes/_bulk_docs
+    Content-Type: application/json
+
+    {
+       "docs" : [
+          {
+             "_id" : "FishStew",
+             "_rev" : "1-9c65296036141e575d32ba9c034dd3ee",
+             "servings" : 4,
+             "subtitle" : "Delicious with freshly baked bread",
+             "title" : "Fish Stew"
+          },
+          {
+             "_id" : "LambStew",
+             "_rev" : "1-34c318924a8f327223eed702ddfdc66d",
+             "servings" : 6,
+             "subtitle" : "Serve with a wholemeal scone topping",
+             "title" : "Lamb Stew"
+          },
+          {
+             "_id" : "7f7638c86173eb440b8890839ff35433"
+             "_rev" : "1-857c7cbeb6c8dd1dd34a0c73e8da3c44",
+             "servings" : 8,
+             "subtitle" : "Hand-made dumplings make a great accompaniment",
+             "title" : "Beef Stew"
+          }
+       ]
+    }
+
+The return structure is the JSON of the updated documents, with the new
+revision and ID information:
+
+::
+
+    [
+       {
+          "id" : "FishStew",
+          "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1"
+       },
+       {
+          "id" : "LambStew",
+          "rev" : "2-0786321986194c92dd3b57dfbfc741ce"
+       },
+       {
+          "id" : "7f7638c86173eb440b8890839ff35433",
+          "rev" : "2-bdd3bf3563bee516b96885a66c743f8e"
+       }
+    ]
+
+You can optionally delete documents during a bulk update by adding the
+``_deleted`` field with a value of ``true`` to each docment ID/revision
+combination within the submitted JSON structure.
+
+The return type from a bulk insertion will be 201, with the content of
+the returned structure indicating specific success or otherwise messages
+on a per-document basis.
+
+The content and structure of the returned JSON will depend on the
+transaction semantics being used for the bulk update; see ? for more
+information. Conflicts and validation errors when updating documents in
+bulk must be handled separately; see ?.
+
+Bulk Documents Transaction Semantics
+------------------------------------
+
+CouchDB supports two different modes for updating (or inserting)
+documents using the bulk documentation system. Each mode affects both
+the state of the documents in the event of system failure, and the level
+of conflict checking performed on each document. The two modes are:
+
+-  ``non-atomic``
+
+   The default mode is non-atomic, that is, CouchDB will only guarantee
+   that some of the documents will be saved when you send the request.
+   The response will contain the list of documents successfully inserted
+   or updated during the process. In the event of a crash, some of the
+   documents may have been successfully saved, and some will have been
+   lost.
+
+   In this mode, the response structure will indicate whether the
+   document was updated by supplying the new ``_rev`` parameter
+   indicating a new document revision was created. If the update failed,
+   then you will get an ``error`` of type ``conflict``. For example:
+
+   ::
+
+       [
+          {
+             "id" : "FishStew",
+             "error" : "conflict",
+             "reason" : "Document update conflict."
+          },
+          {
+             "id" : "LambStew",
+             "error" : "conflict",
+             "reason" : "Document update conflict."
+          },
+          {
+             "id" : "7f7638c86173eb440b8890839ff35433",
+             "error" : "conflict",
+             "reason" : "Document update conflict."
+          }
+       ]
+           
+
+   In this case no new revision has been created and you will need to
+   submit the document update, with the correct revision tag, to update
+   the document.
+
+-  ``all-or-nothing``
+
+   In all-or-nothing mode, either all documents are written to the
+   database, or no documents are written to the database, in the event
+   of a system failure during commit.
+
+   In addition, the per-document conflict checking is not performed.
+   Instead a new revision of the document is created, even if the new
+   revision is in conflict with the current revision in the database.
+   The returned structure contains the list of documents with new
+   revisions:
+
+   ::
+
+       [
+          {
+             "id" : "FishStew",
+             "rev" : "2-e7af4c4e9981d960ecf78605d79b06d1"
+          },
+          {
+             "id" : "LambStew",
+             "rev" : "2-0786321986194c92dd3b57dfbfc741ce"
+          },
+          {
+             "id" : "7f7638c86173eb440b8890839ff35433",
+             "rev" : "2-bdd3bf3563bee516b96885a66c743f8e"
+          }
+       ]
+
+   When updating documents using this mode the revision of a document
+   included in views will be arbitrary. You can check the conflict
+   status for a document by using the ``conflicts=true`` query argument
+   when accessing the view. Conflicts should be handled individually to
+   ensure the consistency of your database.
+
+   To use this mode, you must include the ``all_or_nothing`` field (set
+   to true) within the main body of the JSON of the request.
+
+The effects of different database operations on the different modes are
+summarized in the table below:
+
++--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+
+| Transaction Mode   | Transaction   | Cause                                  | Resolution                                                             |
++====================+===============+========================================+========================================================================+
+| Non-atomic         | Insert        | Requested document ID already exists   | Resubmit with different document ID, or update the existing document   |
++--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+
+| Non-atomic         | Update        | Revision missing or incorrect          | Resubmit with correct revision                                         |
++--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+
+| All-or-nothing     | Insert        | Additional revision inserted           | Resolve conflicted revisions                                           |
++--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+
+| All-or-nothing     | Update        | Additional revision inserted           | Resolve conflicted revisions                                           |
++--------------------+---------------+----------------------------------------+------------------------------------------------------------------------+
+
+Table: Conflicts on Bulk Inserts
+
+Replication of documents is independent of the type of insert or update.
+The documents and revisions created during a bulk insert or update are
+replicated in the same way as any other document. This can mean that if
+you make use of the all-or-nothing mode the exact list of documents,
+revisions (and their conflict state) may or may not be replicated to
+other databases correctly.
+
+Bulk Document Validation and Conflict Errors
+--------------------------------------------
+
+The JSON returned by the ``_bulk_docs`` operation consists of an array
+of JSON structures, one for each document in the original submission.
+The returned JSON structure should be examined to ensure that all of the
+documents submitted in the original request were successfully added to
+the database.
+
+The exact structure of the returned information is shown in ?.
+
+When a document (or document revision) is not correctly comitted to the
+database because of an error, you should check the ``error`` field to
+determine error type and course of action. Errors will be one of the
+following type:
+
+-  ``conflict``
+
+   The document as submitted is in conflict. If you used the default
+   bulk transaction mode then the new revision will not have been
+   created and you will need to re-submit the document to the database.
+   If you used ``all-or-nothing`` mode then you will need to manually
+   resolve the conflicted revisions of the document.
+
+   Conflict resolution of documents added using the bulk docs interface
+   is identical to the resolution procedures used when resolving
+   conflict errors during replication.
+
+-  ``forbidden``
+
+   Entries with this error type indicate that the validation routine
+   applied to the document during submission has returned an error.
+
+   For example, if your validation routine includes the following:
+
+   ::
+
+        throw({forbidden: 'invalid recipe ingredient'});
+
+   The error returned will be:
+
+   ::
+
+       {
+          "id" : "7f7638c86173eb440b8890839ff35433",
+          "error" : "forbidden",
+          "reason" : "invalid recipe ingredient"
+       }
+             
+
+   For more information, see ?.
+
+``POST /db/_temp_view``
+=======================
+
+Creates (and executes) a temporary view based on the view function
+supplied in the JSON request. For example:
+
+::
+
+    POST http://couchdb:5984/recipes/_temp_view
+    Content-Type: application/json
+
+    {
+       "map" : "function(doc) { if (doc.value > 9995) { emit(null, doc.value); } }"
+    }
+
+The resulting JSON response is the result from the execution of the
+temporary view:
+
+::
+
+    {
+       "total_rows" : 3,
+       "rows" : [
+          {
+             "value" : 9998.41913029012,
+             "id" : "05361cc6aa42033878acc1bacb1f39c2",
+             "key" : null
+          },
+          {
+             "value" : 9998.94149934853,
+             "id" : "1f443f471e5929dd7b252417625ed170",
+             "key" : null
+          },
+          {
+             "value" : 9998.01511339154,
+             "id" : "1f443f471e5929dd7b252417629c102b",
+             "key" : null
+          }
+       ],
+       "offset" : 0
+    }
+
+The arguments also available to standard view requests also apply to
+temporary views, but the execution of the view may take some time as it
+relies on being executed at the time of the request. In addition to the
+time taken, they are also computationally very expensive to produce. You
+should use a defined view if you want to achieve the best performance.
+
+For more information, see ?.
+
+``POST /db/_purge``
+===================
+
+A database purge permanently removes the references to deleted documents
+from the database. Deleting a document within CouchDB does not actually
+remove the documen from the database, instead, the document is marked as
+a deleted (and a new revision is created). This is to ensure that
+deleted documents are replicated to other databases as having been
+deleted. This also means that you can check the status of a document and
+identify that the document has been deleted.
+
+The purge operation removes the refernces to the deleted documents from
+the database. The purging of old documents is not replicated to other
+databases. If you are replicating between databases and have deleted a
+large number of documents you should run purge on each database.
+
+    **Note**
+
+    Purging documents does not remove the space used by them on disk. To
+    reclaim disk space, you should run a database compact (see ?, and
+    compact views (see ?).
+
+To perform a purge operation you must send a request including the JSON
+of the document IDs that you want to purge. For example:
+
+::
+
+    POST http://couchdb:5984/recipes/_purge
+    Content-Type: application/json
+
+    {
+      "FishStew" : [
+        "17-b3eb5ac6fbaef4428d712e66483dcb79"
+        ]
+    }
+
+The format of the request must include the document ID and one or more
+revisions that must be purged.
+
+The response will contain the purge sequence number, and a list of the
+document IDs and revisions successfully purged.
+
+::
+
+    {
+       "purged" : {
+          "FishStew" : [
+             "17-b3eb5ac6fbaef4428d712e66483dcb79"
+          ]
+       },
+       "purge_seq" : 11
+    }
+
+Updating Indexes
+----------------
+
+The number of purges on a database is tracked using a purge sequence.
+This is used by the view indexer to optimize the updating of views that
+contain the purged documents.
+
+When the indexer identifies that the purge sequence on a database has
+changed, it compares the purge sequence of the database with that stored
+in the view index. If the difference between the stored sequence and
+database is sequence is only 1, then the indexer uses a cached list of
+the most recently purged documents, and then removes these documents
+from the index individually. This prevents completely rebuilding the
+index from scratch.
+
+If the difference between the stored sequence number and current
+database sequence is greater than 1, then the view index is entirely
+rebuilt. This is an expensive operation as every document in the
+database must be examined.
+
+``GET /db/_all_docs``
+=====================
+
+Returns a JSON structure of all of the documents in a given database.
+The information is returned as a JSON structure containing meta
+information about the return structure, and the list documents and basic
+contents, consisting the ID, revision and key. The key is generated from
+the document ID.
+
+By default the information returned contains only the document ID and
+revision. For example, the request:
+
+::
+
+    GET http://couchdb:5984/recipes/_all_docs
+    Accept: application/json
+
+Returns the following structure:
+
+::
+
+    {
+       "total_rows" : 18386,
+       "rows" : [
+          {
+             "value" : {
+                "rev" : "1-bc0d5aed1e339b1cc1f29578f3220a45"
+             },
+             "id" : "Aberffrawcake",
+             "key" : "Aberffrawcake"
+          },
+          {
+             "value" : {
+                "rev" : "3-68a20c89a5e70357c20148f8e82ca331"
+             },
+             "id" : "Adukiandorangecasserole-microwave",
+             "key" : "Adukiandorangecasserole-microwave"
+          },
+          {
+             "value" : {
+                "rev" : "3-9b2851ed9b6f655cc4eb087808406c60"
+             },
+             "id" : "Aioli-garlicmayonnaise",
+             "key" : "Aioli-garlicmayonnaise"
+          },
+          ...
+             ],
+       "offset" : 0
+    }
+
+The information is returned in the form of a temporary view of all the
+database documents, with the returned key consisting of the ID of the
+document. The remainder of the interface is therefore identical to the
+View query arguments and their behavior.
+
+``POST /db/_all_docs``
+======================
+
+The ``POST`` to ``_all_docs`` allows to specify multiple keys to be
+selected from the database. This enables you to request multiple
+documents in a single request, in place of multiple ? requests.
+
+The request body should contain a list of the keys to be returned as an
+array to a ``keys`` object. For example:
+
+::
+
+    POST http://couchdb:5984/recipes/_all_docs
+    User-Agent: MyApp/0.1 libwww-perl/5.837
+
+    {
+       "keys" : [
+          "Zingylemontart",
+          "Yogurtraita"
+       ]
+    }
+
+The return JSON is the all documents structure, but with only the
+selected keys in the output:
+
+::
+
+    {
+       "total_rows" : 2666,
+       "rows" : [
+          {
+             "value" : {
+                "rev" : "1-a3544d296de19e6f5b932ea77d886942"
+             },
+             "id" : "Zingylemontart",
+             "key" : "Zingylemontart"
+          },
+          {
+             "value" : {
+                "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
+             },
+             "id" : "Yogurtraita",
+             "key" : "Yogurtraita"
+          }
+       ],
+       "offset" : 0
+    }
+
+``POST /db/_missing_revs``
+==========================
+
+``POST /db/_revs_diff``
+=======================
+
+``GET /db/_security``
+=====================
+
+Gets the current secrity object from the specified database. The
+security object consists of two compulsory elements, ``admins`` and
+``readers``, which are used to specify the list of users and/or roles
+that have admin and reader rights to the database respectively. Any
+additional fields in the security object are optional. The entire
+security object is made available to validation and other internal
+functions so that the database can control and limit functionality.
+
+To get the existing security object you would send the following
+request:
+
+::
+
+    {
+       "admins" : {
+          "roles" : [],
+          "names" : [
+             "mc",
+             "slp"
+          ]
+       },
+       "readers" : {
+          "roles" : [],
+          "names" : [
+             "tim",
+             "brian"
+          ]
+       }
+    }
+
+    **Note**
+
+    If the security object for a database has never beent set, then the
+    value returned will be empty.
+
+``PUT /db/_security``
+=====================
+
+Sets the security object for the given database.For example, to set the
+security object for the ``recipes`` database:
+
+::
+
+    PUT http://couchdb:5984/recipes/_security
+    Content-Type: application/json
+
+    {
+       "admins" : {
+          "roles" : [],
+          "names" : [
+             "mc",
+             "slp"
+          ]
+       },
+       "readers" : {
+          "roles" : [],
+          "names" : [
+             "tim",
+             "brian"
+          ]
+       }
+    }
+
+If the setting was successful, a JSON status object will be returned:
+
+::
+
+    {
+       "ok" : true
+    }
+
+``GET /db/_revs_limit``
+=======================
+
+Gets the current ``revs_limit`` (revision limit) setting.
+
+For example to get the current limit:
+
+::
+
+    GET http://couchdb:5984/recipes/_revs_limit
+    Content-Type: application/json
+
+The returned information is the current setting as a numerical scalar:
+
+::
+
+    1000
+
+``PUT /db/_revs_limit``
+=======================
+
+Sets the maximum number of document revisions that will be tracked by
+CouchDB, even after compaction has occurred. You can set the revision
+limit on a database by using ``PUT`` with a scalar integer of the limit
+that you want to set as the request body.
+
+For example to set the revs limit to 100 for the ``recipes`` database:
+
+::
+
+    PUT http://couchdb:5984/recipes/_revs_limit
+    Content-Type: application/json
+
+    100
+
+If the setting was successful, a JSON status object will be returned:
+
+::
+
+    {
+       "ok" : true
+    }
+
+CouchDB API Server 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:
+
+Document API Calls
+
+``POST /db``
+============
+
+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:
+
+::
+
+    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 enerated ID and revision
+information:
+
+::
+
+    {
+       "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``:
+
+::
+
+    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:
+
+::
+
+    {
+       "id" : "FishStew",
+       "ok" : true,
+       "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+    }
+        
+
+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 ?).
+
+The ``filename`` will be the attachment name. For example, when sending
+the JSON structure below:
+
+::
+
+    {
+       "_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 ?.
+
+The document data embedded in to the structure must be encoded using
+base64.
+
+``GET /db/doc``
+===============
+
+Returns the specified ``doc`` from the specified ``db``. For example, to
+retrieve the document with the id ``FishStew`` you would send the
+following request:
+
+::
+
+    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:
+
+::
+
+    {
+       "_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 associatd 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:
+
+::
+
+    {
+       "_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:
+
+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:
+
+::
+
+    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:
+
+::
+
+    {
+       "servings" : 4,
+       "subtitle" : "Delicious with a green salad",
+       "_id" : "FishStew",
+       "title" : "Irish Fish Stew",
+       "_revisions" : {
+          "ids" : [
+             "a1a9b39ee3cc39181b796a69cb48521c",
+             "7c4740b4dcf26683e941d6641c00c39d",
+             "9c65296036141e575d32ba9c034dd3ee"
+          ],
+          "start" : 3
+       },
+       "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c"
+    }
+
+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:
+
+::
+
+    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:
+
+::
+
+    {
+       "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"
+    }
+
+Obtaining a Specific Revision
+-----------------------------
+
+To get a specific revision, use the ``rev`` argument to the request, and
+specify the full revision number:
+
+::
+
+    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:
+
+::
+
+    {
+       "_id" : "FishStew",
+       "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d",
+       "servings" : 4,
+       "subtitle" : "Delicious with a green salad",
+       "title" : "Fish Stew"
+    }
+
+``HEAD /db/doc``
+================
+
+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:
+
+::
+
+    HEAD http://couchdb:5984/recipes/FishStew
+    Content-Type: application/json
+        
+
+Returns the following HTTP Headers:
+
+::
+
+    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:
+
+::
+
+    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
+
+``PUT /db/doc``
+===============
+
+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 docment ``FishStew``, you would send the
+following request:
+
+::
+
+    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:
+
+::
+
+    {
+       "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:
+
+::
+
+    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:
+
+::
+
+    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:
+
+::
+
+    {
+       "id" : "FishStew99",
+       "ok" : true,
+       "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea"
+    }
+
+For information on batched writes, which can provide improved
+performance, see ?.
+
+``DELETE /db/doc``
+==================
+
+Deletes the specified document from the database. You must supply the
+current (latest) revision, either by using the ``rev`` parameter to
+specify the revision:
+
+::
+
+    DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c
+    Content-Type: application/json
+
+Alternatively, you can use ETags with the ``If-Match`` field:
+
+::
+
+    DELETE http://couchdb:5984/recipes/FishStew
+    If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c
+    Content-Type: application/json
+        
+
+The returned JSON contains the document ID, revision and status:
+
+::
+
+    {
+       "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.
+
+``COPY /db/doc``
+================
+
+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:
+
+::
+
+    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.
+
+::
+
+    {
+       "id" : "IrishFishStew",
+       "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
+    }
+
+Copying from a Specific Revision
+--------------------------------
+
+To copy *from* a specific version, use the ``rev`` argument to the query
+string:
+
+::
+
+    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:
+
+::
+
+    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:
+
+::
+
+    {
+       "id" : "IrishFishStew",
+       "rev" : "2-55b6a1b251902a2c249b667dab1c6692"
+    }
+
+``GET /db/doc/attachment``
+==========================
+
+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.
+
+``PUT /db/doc/attachment``
+==========================
+
+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 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:
+
+::
+
+    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:
+
+::
+
+    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:
+
+::
+
+    {
+       "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``
+=============================
+
+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``:
+
+::
+
+    DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74
+    Content-Type: application/json
+
+        
+
+The returned JSON contains the updated revision information:
+
+::
+
+    {
+       "id" : "FishStew",
+       "ok" : true,
+       "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e"
+    }
+
+CouchDB API Server 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``
+==============================
+
+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:
+
+::
+
+    GET http://couchdb:5984/recipes/_design/recipes
+    Content-Type: application/json
+
+The returned string will be the JSON of the design document:
+
+::
+
+    {
+       "_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 ?.
+
+``PUT /db/_design/design-doc``
+==============================
+
+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.
+
+For more information on writing views, see ?.
+
+``DELETE /db/_design/design-doc``
+=================================
+
+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:
+
+::
+
+    DELETE http://couchdb:5984/recipes/_design/recipes?rev=2-ac58d589b37d01c00f45a4418c5a15a8
+    Content-Type: application/json
+
+The response contains the delete document ID and revision:
+
+::
+
+    {
+       "id" : "recipe/_design/recipes"
+       "ok" : true,
+       "rev" : "3-7a05370bff53186cb5d403f861aca154",
+    }
+
+``COPY /db/_design/design-doc``
+===============================
+
+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:
+
+::
+
+    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.
+
+::
+
+    {
+       "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:
+
+::
+
+    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:
+
+::
+
+    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:
+
+::
+
+    {
+       "id" : "recipes/_design/recipes"
+       "rev" : "2-55b6a1b251902a2c249b667dab1c6692",
+    }
+
+``GET /db/_design/design-doc/attachment``
+=========================================
+
+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``
+=========================================
+
+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:
+
+::
+
+    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:
+
+::
+
+    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:
+
+::
+
+    {
+       "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``
+============================================
+
+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``:
+
+::
+
+    DELETE http://couchdb:5984/recipes/_design/recipes/view.css?rev=9-3db559f13a845c7751d407404cdeaa4a
+        
+
+The returned JSON contains the updated revision information for the
+parent document:
+
+::
+
+    {
+       "id" : "_design/recipes"
+       "ok" : true,
+       "rev" : "10-f3b15bb408961f8dcc3d86c7d3b54c4c",
+    }
+
+``GET /db/_design/design-doc/_info``
+====================================
+
+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:
+
+::
+
+    GET http://couchdb:5984/recipes/_design/recipes/_info
+    Content-Type: application/json
+
+This returns the following JSON structure:
+
+::
+
+    {
+       "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 in ?.
+
+Design Document Info JSON Contents
+
+``GET /db/_design/design-doc/_view/view-name``
+==============================================
+
+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 ? 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 ?.
+
+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:
+
+::
+
+    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``
+paramater. 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 ?).
+
+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:
+
+::
+
+    {
+       "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
+
+::
+
+    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:
+
+::
+
+    {
+       "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:
+
+::
+
+    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:
+
+::
+
+    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:
+
+::
+
+    {
+       "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:
+
+::
+
+    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
+-------------------------------
+
+The ``startkey`` and ``endkey`` query arguments can be used to specify
+the range of values to be displayed when querying the view.
+
+    **Note**
+
+    The values
+
+Using Limits and Skipping Rows
+------------------------------
+
+TBC
+
+View Reduction and Grouping
+---------------------------
+
+TBC
+
+``POST /db/_design/design-doc/_view/view-name``
+===============================================
+
+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 ? fun
+
+For example, the request below will return all the recipes where the key
+for the view matches either “claret” or “clear apple cider” :
+
+::
+
+    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.
+
+::
+
+    {
+       "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 ?
+requests.
+
+For example, sending the following request for ingredients matching
+“claret” and “clear apple juice”:
+
+::
+
+    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:
+
+::
+
+    {
+       "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
+    }
+
+``POST /db/_design/design-doc/_show/show-name``
+===============================================
+
+``POST /db/_design/design-doc/_show/show-name/doc``
+===================================================
+
+``GET
+      /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
+=========================================================================
+
+``POST
+      /db/_design/design-doc/_list/list-name/other-design-doc/view-name``
+=========================================================================
+
+``GET /db/_design/design-doc/_list/list-name/view-name``
+========================================================
+
+``POST /db/_design/design-doc/_list/list-name/view-name``
+=========================================================
+
+``PUT /db/_design/design-doc/_update/updatename/doc``
+=====================================================
+
+``POST /db/_design/design-doc/_update/updatename``
+==================================================
+
+``ALL
+      /db/_design/design-doc/_rewrite/rewrite-name/anything``
+=============================================================
+
+CouchDB API
+===========
+
+The CouchDB API is the primary method of interfacing to a CouchDB
+instance. Requests are made using HTTP and requests are used to request
+information from the database, store new data, and perform views and
+formatting of the information stored within the documents.
+
+Requests to the API can be categorised by the different areas of the
+CouchDB system that you are accessing, and the HTTP method used to send
+the request. Different methods imply different operations, for example
+retrieval of information from the database is typically handled by the
+``GET`` operation, while updates are handled by either a ``POST`` or
+``PUT`` request. There are some differences between the information that
+must be supplied for the different methods. For a guide to the basic
+HTTP methods and request structure, see ?.
+
+For nearly all operations, the submitted data, and the returned data
+structure, is defined within a JavaScript Object Notation (JSON) object.
+Basic information on the content and data types for JSON are provided in
+?.
+
+Errors when accessing the CouchDB API are reported using standard HTTP
+Status Codes. A guide to the generic codes returned by CouchDB are
+provided in ?.
+
+When accessing specific areas of the CouchDB API, specific information
+and examples on the HTTP methods and request, JSON structures, and error
+codes are provided. For a guide to the different areas of the API, see
+?.
+
+Request Format and Responses
+============================
+
+CouchDB supports the following HTTP request methods:
+
+-  ``GET``
+
+   Request the specified item. As with normal HTTP requests, the format
+   of the URL defines what is returned. With CouchDB this can include
+   static items, database documents, and configuration and statistical
+   information. In most cases the information is returned in the form of
+   a JSON document.
+
+-  ``HEAD``
+
+   The ``HEAD`` method is used to get the HTTP header of a ``GET``
+   request without the body of the response.
+
+-  ``POST``
+
+   Upload data. Within CouchDB ``POST`` is used to set values, including
+   uploading documents, setting document values, and starting certain
+   administration commands.
+
+-  ``PUT``
+
+   Used to put a specified resource. In CouchDB ``PUT`` is used to
+   create new objects, including databases, documents, views and design
+   documents.
+
+-  ``DELETE``
+
+   Deletes the specified resource, including documents, views, and
+   design documents.
+
+-  ``COPY``
+
+   A special method that can be used to copy documents and objects.
+
+If you use the an unsupported HTTP request type with a URL that does not
+support the specified type, a 405 error will be returned, listing the
+supported HTTP methods. For example:
+
+::
+
+    {
+        "error":"method_not_allowed",
+        "reason":"Only GET,HEAD allowed"
+    }
+          
+
+The CouchDB design document API and the functions when returning HTML
+(for example as part of a show or list) enables you to include custom
+HTTP headers through the ``headers`` block of the return object. For
+more information, see ?.
+
+HTTP Headers
+============
+
+Because CouchDB uses HTTP for all communication, you need to ensure that
+the correct HTTP headers are supplied (and processed on retrieval) so
+that you get the right format and encoding. Different environments and
+clients will be more or less strict on the effect of these HTTP headers
+(especially when not present). Where possible you should be as specific
+as possible.
+
+Request Headers
+---------------
+
+-  ``Content-type``
+
+   Specifies the content type of the information being supplied within
+   the request. The specification uses MIME type specifications. For the
+   majority of requests this will be JSON (``application/json``). For
+   some settings the MIME type will be plain text. When uploading
+   attachments it should be the corresponding MIME type for the
+   attachment or binary (``application/octet-stream``).
+
+   The use of the ``Content-type`` on a request is highly recommended.
+
+-  ``Accept``
+
+   Specifies the list of accepted data types to be returned by the
+   server (i.e. that are accepted/understandable by the client). The
+   format should be a list of one or more MIME types, separated by
+   colons.
+
+   For the majority of requests the definition should be for JSON data
+   (``application/json``). For attachments you can either specify the
+   MIME type explicitly, or use ``*/*`` to specify that all file types
+   are supported. If the ``Accept`` header is not supplied, then the
+   ``*/*`` MIME type is assumed (i.e. client accepts all formats).
+
+   The use of ``Accept`` in queries for CouchDB is not required, but is
+   highly recommended as it helps to ensure that the data returned can
+   be processed by the client.
+
+   If you specify a data type using the ``Accept`` header, CouchDB will
+   honor the specified type in the ``Content-type`` header field
+   returned. For example, if you explicitly request ``application/json``
+   in the ``Accept`` of a request, the returned HTTP headers will use
+   the value in the returned ``Content-type`` field.
+
+   For example, when sending a request without an explicit ``Accept``
+   header, or when specifying ``*/*``:
+
+   ::
+
+       GET /recipes HTTP/1.1
+       Host: couchdb:5984
+       Accept: */*
+
+   The returned headers are:
+
+   ::
+
+       Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+       Date: Thu, 13 Jan 2011 13:39:34 GMT
+       Content-Type: text/plain;charset=utf-8
+       Content-Length: 227
+       Cache-Control: must-revalidate
+
+   Note that the returned content type is ``text/plain`` even though the
+   information returned by the request is in JSON format.
+
+   Explicitly specifying the ``Accept`` header:
+
+   ::
+
+       GET /recipes HTTP/1.1
+       Host: couchdb:5984
+       Accept: application/json
+
+   The headers returned include the ``application/json`` content type:
+
+   ::
+
+       Server: CouchDB/1.0.1 (Erlang OTP/R13B)
+       Date: Thu, 13 Jan 2011 13:40:11 GMT
+       Content-Type: application/json
+       Content-Length: 227
+       Cache-Control: must-revalidate
+
+Response Headers
+----------------
+
+Response headers are returned by the server when sending back content
+and include a number of different header fields, many of which are
+standard HTTP response header and have no significance to CouchDB
+operation. The list of response headers important to CouchDB are listed
+below.
+
+-  ``Content-type``
+
+   Specifies the MIME type of the returned data. For most request, the
+   returned MIME type is ``text/plain``. All text is encoded in Unicode
+   (UTF-8), and this is explicitly stated in the returned
+   ``Content-type``, as ``text/plain;charset=utf-8``.
+
+-  ``Cache-control``
+
+   The cache control HTTP response header provides a suggestion for
+   client caching mechanisms on how to treat the returned information.
+   CouchDB typically returns the ``must-revalidate``, which indicates
+   that the information should be revalidated if possible. This is used
+   to ensure that the dynamic nature of the content is correctly
+   updated.
+
+-  ``Content-length``
+
+   The length (in bytes) of the returned content.
+
+-  ``Etag``
+
+   The ``Etag`` HTTP header field is used to show the revision for a
+   document.
+
+JSON Basics
+===========
+
+The majority of requests and responses to CouchDB use the JavaScript
+Object Notation (JSON) for formatting the content and structure of the
+data and responses.
+
+JSON is used because it is the simplest and easiest to use solution for
+working with data within a web browser, as JSON structures can be
+evaluated and used as JavaScript objects within the web browser
+environment. JSON also integrates with the server-side JavaScript used
+within CouchDB.
+
+JSON supports the same basic types as supported by JavaScript, these
+are:
+
+-  Number (either integer or floating-point).
+
+-  String; this should be enclosed by double-quotes and supports Unicode
+   characters and backslash escaping. For example:
+
+   ::
+
+       "A String"
+
+-  Boolean - a ``true`` or ``false`` value. You can use these strings
+   directly. For example:
+
+   ::
+
+       { "value": true}
+
+-  Array - a list of values enclosed in square brackets. For example:
+
+   ::
+
+       ["one", "two", "three"]
+
+-  Object - a set of key/value pairs (i.e. an associative array, or
+   hash). The key must be a string, but the value can be any of the
+   supporte

<TRUNCATED>

Mime
View raw message