couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [26/34] import Couchbase docs
Date Wed, 12 Dec 2012 20:33:59 GMT
http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
----------------------------------------------------------------------
diff --git a/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml b/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
new file mode 100644
index 0000000..8667927
--- /dev/null
+++ b/share/docs/couchdb-manual-1.1/couchdb-manual-ready.xml
@@ -0,0 +1,9409 @@
+<?xml version="1.0" encoding="utf-8" standalone="no"?>
+<book id="couchdb-1-1">
+
+  <title>CouchDB 1.1 Manual</title>
+
+  <bookinfo>
+
+    <abstract>
+
+      <para>
+        This manual documents the CouchDB
+        1.1 database system, including the installation,
+        functionality, and CouchDB API.
+      </para>
+
+      <para xml:base="../common/docbuilddate.xml">
+  <emphasis>Last document update</emphasis>: 21 Feb 2012 20:09;
+  <emphasis>Document built</emphasis>: 21 Feb 2012 20:9.
+</para>
+
+    </abstract>
+
+  </bookinfo>
+
+  <chapter id="couchdb-single-introduction">
+
+  <title>Introduction</title>
+
+  <para>
+    There are two interfaces to CouchDB, the built-in
+    Futon web-based interface and the CouchDB API accessed through the
+    HTTP REST interface. The former is the simplest way to view and
+    monitor your CouchDB installation and perform a
+    number of basic database and system operations. More information on
+    using the Futon interface can be found in
+    <xref linkend="couchdb-single-introduction-futon"/>.
+  </para>
+
+  <para>
+    The primary way to interact with the CouchDB API is to use a client
+    library or other interface that provides access to the underlying
+    functionality through your chosen language or platform. However,
+    since the API is supported through HTTP REST, you can interact with
+    your CouchDB with any solution that supports the
+    HTTP protocol.
+  </para>
+
+  <para>
+    There are a number of different tools that talk the HTTP protocol
+    and allow you to set and configure the necessary information. One
+    tool for this that allows for access from the command-line is
+    <command moreinfo="none">curl</command>. See
+    <xref linkend="couchdb-single-introduction-curl"/>.
+  </para>
+
+  <section id="couchdb-single-introduction-futon">
+
+    <title>Using Futon</title>
+
+    <para>
+      Futon is a native web-based interface built into CouchDB. It provides a basic interface to the majority of the
+      functionality, including the ability to create, update, delete and
+      view documents and views, provides access to the configuration
+      parameters, and an interface for initiating replication.
+    </para>
+
+    <para>
+      The default view is the <guilabel moreinfo="none">Overview</guilabel> page which
+      provides you with a list of the databases. The basic structure of
+      the page is consistent regardless of the section you are in. The
+      main panel on the left provides the main interface to the
+      databases, configuration or replication systems. The side panel on
+      the right provides navigation to the main areas of Futon
+      interface:
+    </para>
+
+    <figure id="fig-ccouchdb-single-introduction-futon-overview" float="0">
+
+      <title>Futon Overview</title>
+
+      <mediaobject>
+
+        <imageobject>
+
+          <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-overview.png" format="PNG" lang="en"/>
+
+        </imageobject>
+
+        <textobject>
+
+          <phrase lang="en">Futon Overview</phrase>
+
+        </textobject>
+
+      </mediaobject>
+
+    </figure>
+
+    <para>
+      The main sections are:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <guibutton moreinfo="none">Overview</guibutton>
+        </para>
+
+        <para>
+          The main overview page, which provides a list of the databases
+          and provides the interface for querying the database and
+          creating and updating documents. See
+          <xref linkend="couchdb-single-introduction-futon-dbdocs"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <guibutton moreinfo="none">Configuration</guibutton>
+        </para>
+
+        <para>
+          An interface into the configuration of your CouchDB installation. The interface allows you to edit the
+          different configurable parameters. For more details on
+          configuration, see
+          <xref linkend="couchdb-single-configuration"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <guibutton moreinfo="none">Replicator</guibutton>
+        </para>
+
+        <para>
+          An interface to the replication system, enabling you to
+          initiate replication between local and remote databases. See
+          <xref linkend="couchdb-single-introduction-futon-replication"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <guibutton moreinfo="none">Status</guibutton>
+        </para>
+
+        <para>
+          Displays a list of the running background tasks on the server.
+          Background tasks include view index building, compaction and
+          replication. The <guibutton moreinfo="none">Status</guibutton> page is an
+          interface to the
+          <link linkend="couchdb-api-misc_active-tasks_get">Active
+          Tasks</link> API call. See
+          <xref linkend="couchdb-api-misc_active-tasks_get"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <guibutton moreinfo="none">Verify Installation</guibutton>
+        </para>
+
+        <para>
+          The <guibutton moreinfo="none">Verify Installation</guibutton> allows you to
+          check whether all of the components of your CouchDB installation are correctly installed.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <guibutton moreinfo="none">Test Suite</guibutton>
+        </para>
+
+        <para>
+          The <guibutton moreinfo="none">Test Suite</guibutton> section allows you to
+          run the built-in test suite. This executes a number of test
+          routines entirely within your browser to test the API and
+          functionality of your CouchDB installation. If
+          you select this page, you can run the tests by using the
+          <guibutton moreinfo="none">Run All</guibutton> button. This will execute all
+          the tests, which may take some time.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <section id="couchdb-single-introduction-futon-dbdocs">
+
+      <title>Managing Databases and Documents</title>
+
+      <para>
+        You can manage databases and documents within Futon using the
+        main <guibutton moreinfo="none">Overview</guibutton> section of the Futon
+        interface.
+      </para>
+
+      <para>
+        To create a new database, click the <guibutton moreinfo="none">Create Database
+        …</guibutton> button. You will be prompted for the
+        database name, as shown in the figure below.
+      </para>
+
+      <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-createdb" float="0">
+
+        <title>Creating a Database</title>
+
+        <mediaobject>
+
+          <imageobject>
+
+            <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-createdb.png" format="PNG" lang="en"/>
+
+          </imageobject>
+
+          <textobject>
+
+            <phrase lang="en">Creating a Database</phrase>
+
+          </textobject>
+
+        </mediaobject>
+
+      </figure>
+
+      <para>
+        Once you have created the database (or selected an existing
+        one), you will be shown a list of the current documents. If you
+        create a new document, or select an existing document, you will
+        be presented with the edit document display.
+      </para>
+
+      <para>
+        Editing documents within Futon requires selecting the document
+        and then editing (and setting) the fields for the document
+        individually before saving the document back into the database.
+      </para>
+
+      <para>
+        For example, the figure below shows the editor for a single
+        document, a newly created document with a single ID, the
+        document <literal moreinfo="none">_id</literal> field.
+      </para>
+
+      <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-editdoc" float="0">
+
+        <title>Editing a Document</title>
+
+        <mediaobject>
+
+          <imageobject>
+
+            <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editdoc.png" format="PNG" lang="en"/>
+
+          </imageobject>
+
+          <textobject>
+
+            <phrase lang="en">Editing a Document</phrase>
+
+          </textobject>
+
+        </mediaobject>
+
+      </figure>
+
+      <para>
+        To add a field to the document:
+      </para>
+
+      <orderedlist inheritnum="ignore" continuation="restarts">
+
+        <listitem>
+          <para>
+            Click <guibutton moreinfo="none">Add Field</guibutton>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            In the fieldname box, enter the name of the field you want
+            to create. For example, <quote>company</quote>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Click the green tick next to the field name to confirm the
+            field name change.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Double-click the corresponding <guilabel moreinfo="none">Value</guilabel>
+            cell.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Enter a company name, for example <quote>Example</quote>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Click the green tick next to the field value to confirm the
+            field value.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            The document is still not saved as this point. You must
+            explicitly save the document by clicking the <guibutton moreinfo="none">Save
+            Document</guibutton> button at the top of the page. This
+            will save the document, and then display the new document
+            with the saved revision information (the
+            <literal moreinfo="none">_rev</literal> field).
+          </para>
+
+          <figure id="fig-ccouchdb-single-introduction-futon-dbdocs-finaldoc" float="0">
+
+            <title>Edited Document</title>
+
+            <mediaobject>
+
+              <imageobject>
+
+                <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-editeddoc.png" format="PNG" lang="en"/>
+
+              </imageobject>
+
+              <textobject>
+
+                <phrase lang="en">Edited Document</phrase>
+
+              </textobject>
+
+            </mediaobject>
+
+          </figure>
+        </listitem>
+
+      </orderedlist>
+
+      <para>
+        The same basic interface is used for all editng operations
+        within Futon. You <emphasis>must</emphasis> rememmbr to save the
+        individual element (fieldname, value) using the green tick
+        button, before then saving the document.
+      </para>
+
+    </section>
+
+    <section id="couchdb-single-introduction-futon-replication">
+
+      <title>Configuring Replication</title>
+
+      <para>
+        When you click the <guibutton moreinfo="none">Replicator</guibutton> option
+        within the <guilabel moreinfo="none">Tools</guilabel> menu you are presented
+        with the Replicator screen. This allows you to start replication
+        between two databases by filling in or select the appropriate
+        options within the form provided.
+      </para>
+
+      <figure id="fig-ccouchdb-single-introduction-futon-replication-form" float="0">
+
+        <title>Replication Form</title>
+
+        <mediaobject>
+
+          <imageobject>
+
+            <imagedata width="100%" contentdepth="100%" scalefit="1" fileref="images/futon-replform.png" format="PNG" lang="en"/>
+
+          </imageobject>
+
+          <textobject>
+
+            <phrase lang="en">Replication Form</phrase>
+
+          </textobject>
+
+        </mediaobject>
+
+      </figure>
+
+      <para>
+        To start a replication process, either the select the local
+        database or enter a remote database name into the corresponding
+        areas of the form. Replication occurs from the database on the
+        left to the database on the right.
+      </para>
+
+      <para>
+        If you are specifying a remote database name, you must specify
+        the full URL of the remote database (including the host, port
+        number and database name). If the remote instance requires
+        authentication, you can specify the username and password as
+        part of the URL, for example
+        <literal moreinfo="none">http://username:pass@remotehost:5984/demo</literal>.
+      </para>
+
+      <para>
+        To enable continuous replication, click the
+        <guilabel moreinfo="none">Continuous</guilabel> checkbox.
+      </para>
+
+      <para>
+        To start the replication process, click the
+        <guibutton moreinfo="none">Replicate</guibutton> button. The replication process
+        should start and will continue in the background. If the
+        replication process will take a long time, you can monitor the
+        status of the replication using the
+        <guibutton moreinfo="none">Status</guibutton> option under the
+        <guilabel moreinfo="none">Tools</guilabel> menu.
+      </para>
+
+      <para>
+        Once replication has been completed, the page will show the
+        information returned when the replication process completes by
+        the API.
+      </para>
+
+      <para>
+        The <guilabel moreinfo="none">Replicator</guilabel> tool is an interface to the
+        underlying replication API. For more information, see
+        <xref linkend="couchdb-api-misc_replicate_post"/>.
+        For more information on replication, see
+        <xref linkend="couchdb-single-replication"/>.
+      </para>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-single-introduction-curl">
+
+    <title>Using <command moreinfo="none">curl</command></title>
+
+    <para>
+      The <command moreinfo="none">curl</command> utility is a command line tool
+      available on Unix, Linux, Mac OS X and Windows and many other
+      platforms. <command moreinfo="none">curl</command> provides easy access to the
+      HTTP protocol (among others) directly from the command-line and is
+      therefore an ideal way of interacting with CouchDB
+      over the HTTP REST API.
+    </para>
+
+    <para>
+      For simple <literal moreinfo="none">GET</literal> requests you can supply the URL
+      of the request. For example, to get the database information:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl http://127.0.0.1:5984</userinput></programlisting>
+
+    <para>
+      This returns the database information (formatted in the output
+      below for clarity):
+    </para>
+
+<programlisting format="linespecific">{
+   "modules" : {
+      "geocouch" : "7fd793c10f3aa667a1088a937398bc5b51472b7f"
+   },
+   "couchdb" : "Welcome",
+   "version" : "1.1.0",
+}</programlisting>
+
+    <note>
+      <para>
+        For some URLs, especially those that include special characters
+        such as ampersand, exclamation mark, or question mark, you
+        should quote the URL you are specifying on the command line. For
+        example:
+      </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl 'http://couchdb:5984/_uuids?count=5'</userinput></programlisting>
+    </note>
+
+    <para>
+      You can explicitly set the HTTP command using the
+      <option>-X</option> command line option. For example, when
+      creating a database, you set the name of the database in the URL
+      you send using a PUT request:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/demo</userinput>
+{"ok":true}</programlisting>
+
+    <para>
+      But to obtain the database information you use a
+      <literal moreinfo="none">GET</literal> request (with the return information
+      formatted for clarity):
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo</userinput>
+{
+   "compact_running" : false,
+   "doc_count" : 0,
+   "db_name" : "demo",
+   "purge_seq" : 0,
+   "committed_update_seq" : 0,
+   "doc_del_count" : 0,
+   "disk_format_version" : 5,
+   "update_seq" : 0,
+   "instance_start_time" : "1306421773496000",
+   "disk_size" : 79
+}</programlisting>
+
+    <para>
+      For certain operations, you must specify the content type of
+      request, which you do by specifying the
+      <literal moreinfo="none">Content-Type</literal> header using the
+      <option>-H</option> command-line option:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -H 'Content-type: application/json' http://127.0.0.1:5984/_uuids</userinput></programlisting>
+
+    <para>
+      You can also submit 'payload' data, that is, data in the body of
+      the HTTP request using the <option>-d</option> option. This is
+      useful if you need to submit JSON structures, for example document
+      data, as part of the request. For example, to submit a simple
+      document to the <literal moreinfo="none">demo</literal> database:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -H 'Content-type: application/json' \
+     -X POST http://127.0.0.1:5984/demo \
+     -d '{"company": "Example, Inc."}'</userinput>
+{"ok":true,"id":"8843faaf0b831d364278331bc3001bd8",
+ "rev":"1-33b9fbce46930280dab37d672bbc8bb9"}</programlisting>
+
+    <para>
+      In the above example, the argument after the <option>-d</option>
+      option is the JSON of the document we want to submit.
+    </para>
+
+    <para>
+      The document can be accessed by using the automatically generated
+      document ID that was returned:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/demo/8843faaf0b831d364278331bc3001bd8</userinput>
+{"_id":"8843faaf0b831d364278331bc3001bd8",
+ "_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
+ "company":"Example, Inc."}</programlisting>
+
+    <para>
+      The API samples in the <xref linkend="couchdb-api-basics"/> show
+      the HTTP command, URL and any payload information that needs to be
+      submitted (and the expected return value). All of these examples
+      can be reproduced using <command moreinfo="none">curl</command> with the
+      command-line examples shown above.
+    </para>
+
+  </section>
+
+</chapter>
+
+  <chapter id="couchdb-single-features">
+
+  <title>Features and Functionality</title>
+
+  <para>
+     
+  </para>
+
+  <section id="couchdb-single-features-httprange">
+
+    <title>HTTP Range Requests</title>
+
+    <para>
+      HTTP allows you to specify byte ranges for requests. This allows
+      the implementation of resumable downloads and skippable audio and
+      video streams alike. The following example uses a text file to
+      make the range request process easier.
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">cat file.txt</userinput>
+My hovercraft is full of eels!</programlisting>
+
+    <para>
+      Uploading this as an attachment to a <literal moreinfo="none">text</literal>
+      database using <command moreinfo="none">curl</command>:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
+    -H "Content-Type: application/octet-stream" -d@file.txt</userinput>
+{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}</programlisting>
+
+    <para>
+      Requesting the whole file works as normal:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt</userinput>
+My hovercraft is full of eels!</programlisting>
+
+    <para>
+      But to retrieve only the first 13 bytes using
+      <command moreinfo="none">curl</command>:
+    </para>
+
+<programlisting format="linespecific">shell&gt; <userinput moreinfo="none">curl -X GET http://127.0.0.1:5984/test/doc/file.txt -H "Range: bytes=0-12"</userinput>
+My hovercraft</programlisting>
+
+    <para>
+      HTTP supports many ways to specify single and even multiple byte
+      rangers. See
+      <ulink url="http://tools.ietf.org/html/rfc2616#section-14.27">RFC
+      2616</ulink>.
+    </para>
+
+    <note>
+      <para>
+        Databases that have been created with CouchDB 1.0.2 or earlier
+        will support range requests in 1.1.0, but they are using a
+        less-optimal algorithm. If you plan to make heavy use of this
+        feature, make sure to compact your database with CouchDB 1.1.0
+        to take advantage of a better algorithm to find byte ranges.
+      </para>
+    </note>
+
+  </section>
+
+  <section id="couchdb-single-features-proxying">
+
+    <title>HTTP Proxying</title>
+
+    <para>
+      The HTTP proxy feature makes it easy to map and redirect different
+      content through your CouchDB URL. The proxy works by mapping a
+      pathname and passing all content after that prefix through to the
+      configured proxy address.
+    </para>
+
+    <para>
+      Configuration of the proxy redirect is handled through the
+      <literal moreinfo="none">[httpd_global_handlers]</literal> section of the CouchDB
+      configuration file (typically <filename moreinfo="none">local.ini</filename>). The
+      format is:
+    </para>
+
+<programlisting format="linespecific">[httpd_global_handlers]
+PREFIX = {couch_httpd_proxy, handle_proxy_req, &lt;&lt;"DESTINATION"&gt;&gt;}</programlisting>
+
+    <para>
+      Where:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">PREFIX</literal>
+        </para>
+
+        <para>
+          Is the string that will be matched. The string can be any
+          valid qualifier, although to ensure that existing database
+          names are not overridden by a proxy configuration, you can use
+          an underscore prefix.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">DESTINATION</literal>
+        </para>
+
+        <para>
+          The fully-qualified URL to which the request should be sent.
+          The destination must include the <literal moreinfo="none">http</literal>
+          prefix. The content is used verbatim in the original request,
+          so you can also forward to servers on different ports and to
+          specific paths on the target host.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      The proxy process then translates requests of the form:
+    </para>
+
+<programlisting format="linespecific">http://couchdb:5984/PREFIX/path</programlisting>
+
+    <para>
+      To:
+    </para>
+
+<programlisting format="linespecific">DESTINATION/path</programlisting>
+
+    <note>
+      <para>
+        Everything after <literal moreinfo="none">PREFIX</literal> including the
+        required forward slash will be appended to the
+        <literal moreinfo="none">DESTINATION</literal>.
+      </para>
+    </note>
+
+    <para>
+      The response is then communicated back to the original client.
+    </para>
+
+    <para>
+      For example, the following configuration:
+    </para>
+
+<programlisting format="linespecific">_google = {couch_httpd_proxy, handle_proxy_req, &lt;&lt;"http://www.google.com"&gt;&gt;}</programlisting>
+
+    <para>
+      Would forward all requests for
+      <literal moreinfo="none">http://couchdb:5984/_google</literal> to the Google
+      website.
+    </para>
+
+    <para>
+      The service can also be used to forward to related CouchDB
+      services, such as Lucene:
+    </para>
+
+<programlisting format="linespecific">[httpd_global_handlers]
+_fti = {couch_httpd_proxy, handle_proxy_req, &lt;&lt;"http://127.0.0.1:5985"&gt;&gt;}</programlisting>
+
+    <note>
+      <para>
+        The proxy service is basic. If the request is not identified by
+        the <literal moreinfo="none">DESTINATION</literal>, or the remainder of the
+        <literal moreinfo="none">PATH</literal> specification is incomplete, the
+        original request URL is interpreted as if the
+        <literal moreinfo="none">PREFIX</literal> component of that URL does not exist.
+      </para>
+
+      <para>
+        For example, requesting
+        <literal moreinfo="none">http://couchdb:5984/_intranet/media</literal> when
+        <filename moreinfo="none">/media</filename> on the proxy destination does not
+        exist, will cause the request URL to be interpreted as
+        <literal moreinfo="none">http://couchdb:5984/media</literal>. Care should be
+        taken to ensure that both requested URLs and destination URLs
+        are able to cope
+      </para>
+    </note>
+
+  </section>
+
+  <section id="couchdb-single-features-commonjs">
+
+    <title>CommonJS support for map functions</title>
+
+    <para>
+      CommonJS support allows you to use CommonJS notation inside
+      <methodname>map</methodname> and <methodname>reduce</methodname>
+      functions, but only of libraries that are stored inside the views
+      part of the design doc.
+    </para>
+
+    <para>
+      So you could continue to access CommonJS code in design_doc.foo,
+      from your list functions etc, but we'd add the ability to require
+      CommonJS modules within map and reduce, but only from
+      <filename moreinfo="none">design_doc.views.lib</filename>.
+    </para>
+
+    <para>
+      There's no worry here about namespace collisions, as Couch just
+      plucks <literal moreinfo="none">views.*.map</literal> and
+      <literal moreinfo="none">views.*.reduce</literal> out of the design doc. So you
+      could have a view called <literal moreinfo="none">lib</literal> if you wanted, and
+      still have CommonJS stored in <literal moreinfo="none">views.lib.sha1</literal>
+      and <literal moreinfo="none">views.lib.stemmer</literal> if you wanted.
+    </para>
+
+    <para>
+      The implementation is simplified by enforcing that CommonJS
+      modules to be used in <methodname>map</methodname> functions be
+      stored in views.lib.
+    </para>
+
+    <para>
+      A sample design doc (taken from the test suite in Futon) is below:
+    </para>
+
+<programlisting format="linespecific">{
+   "views" : {
+      "lib" : {
+         "baz" : "exports.baz = 'bam';",
+         "foo" : {
+            "zoom" : "exports.zoom = 'yeah';",
+            "boom" : "exports.boom = 'ok';",
+            "foo" : "exports.foo = 'bar';"
+         }
+      },
+      "commonjs" : {
+         "map" : "function(doc) { emit(null, require('views/lib/foo/boom').boom)}"
+      }
+   },
+   "_id" : "_design/test"
+}</programlisting>
+
+    <para>
+      The <literal moreinfo="none">require()</literal> statement is relative to the
+      design document, but anything loaded form outside of
+      <literal moreinfo="none">views/lib</literal> will fail.
+    </para>
+
+  </section>
+
+  <section id="couchdb-single-features-etag">
+
+    <title>Granular ETag support</title>
+
+    <para>
+      ETags have been assigned to a map/reduce group (the collection of
+      views in a single design document). Any change to any of the
+      indexes for those views would generate a new ETag for all view
+      URL's in a single design doc, even if that specific view's results
+      had not changed.
+    </para>
+
+    <para>
+      In CouchDB 1.1 each <literal moreinfo="none">_view</literal> URL has it's own ETag
+      which only gets updated when changes are made to the database that
+      effect that index. If the index for that specific view does not
+      change, that view keeps the original ETag head (therefore sending
+      back 304 Not Modified more often).
+    </para>
+
+  </section>
+
+</chapter>
+
+  <chapter id="couchdb-single-replication">
+
+  <title>Replication</title>
+
+  <para>
+     
+  </para>
+
+  <section id="couchdb-single-replication-replicatordb">
+
+    <title>Replicator Database</title>
+
+    <para>
+      A database where you
+      <literal moreinfo="none">PUT</literal>/<literal moreinfo="none">POST</literal> documents to
+      trigger replications and you <literal moreinfo="none">DELETE</literal> to cancel
+      ongoing replications. These documents have exactly the same
+      content as the JSON objects we used to <literal moreinfo="none">POST</literal> to
+      <literal moreinfo="none">_replicate</literal> (fields <literal moreinfo="none">source</literal>,
+      <literal moreinfo="none">target</literal>, <literal moreinfo="none">create_target</literal>,
+      <literal moreinfo="none">continuous</literal>, <literal moreinfo="none">doc_ids</literal>,
+      <literal moreinfo="none">filter</literal>, <literal moreinfo="none">query_params</literal>.
+    </para>
+
+    <para>
+      Replication documents can have a user defined
+      <literal moreinfo="none">_id</literal>. Design documents (and
+      <literal moreinfo="none">_local</literal> documents) added to the replicator
+      database are ignored.
+    </para>
+
+    <para>
+      The default name of this database is
+      <literal moreinfo="none">_replicator</literal>. The name can be changed in the
+      <filename moreinfo="none">local.ini</filename> configuration, section
+      <literal moreinfo="none">[replicator]</literal>, parameter <literal moreinfo="none">db</literal>.
+    </para>
+
+    <section id="couchdb-single-replication-replicatordb-basics">
+
+      <title>Basics</title>
+
+      <para>
+        Let's say you PUT the following document into _replicator:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "my_rep",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar",
+    "create_target":  true
+}</programlisting>
+
+      <para>
+        In the couch log you'll see 2 entries like these:
+      </para>
+
+<programlisting format="linespecific">[Thu, 17 Feb 2011 19:43:59 GMT] [info] [&lt;0.291.0&gt;] Document `my_rep` triggered replication `c0ebe9256695ff083347cbf95f93e280+create_target`
+[Thu, 17 Feb 2011 19:44:37 GMT] [info] [&lt;0.124.0&gt;] Replication `c0ebe9256695ff083347cbf95f93e280+create_target` finished (triggered by document `my_rep`)</programlisting>
+
+      <para>
+        As soon as the replication is triggered, the document will be
+        updated by CouchDB with 3 new fields:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "my_rep",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar",
+    "create_target":  true,
+    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+    "_replication_state":  "triggered",
+    "_replication_state_time":  1297974122
+}</programlisting>
+
+      <para>
+        Special fields set by the replicator start with the prefix
+        <literal moreinfo="none">_replication_</literal>.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">_replication_id</literal>
+          </para>
+
+          <para>
+            The ID internally assigned to the replication. This is also
+            the ID exposed by <literal moreinfo="none">/_active_tasks</literal>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">_replication_state</literal>
+          </para>
+
+          <para>
+            The current state of the replication.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">_replication_state_time</literal>
+          </para>
+
+          <para>
+            A Unix timestamp (number of seconds since 1 Jan 1970) that
+            tells us when the current replication state (marked in
+            <literal moreinfo="none">_replication_state</literal>) was set.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        When the replication finishes, it will update the
+        <literal moreinfo="none">_replication_state</literal> field (and
+        <literal moreinfo="none">_replication_state_time</literal>) with the value
+        <literal moreinfo="none">completed</literal>, so the document will look like:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "my_rep",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar",
+    "create_target":  true,
+    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+    "_replication_state":  "completed",
+    "_replication_state_time":  1297974122
+}</programlisting>
+
+      <para>
+        When an error happens during replication, the
+        <literal moreinfo="none">_replication_state</literal> field is set to
+        <literal moreinfo="none">error</literal> (and
+        <literal moreinfo="none">_replication_state</literal> gets updated of course).
+      </para>
+
+      <para>
+        When you PUT/POST a document to the
+        <literal moreinfo="none">_replicator</literal> database, CouchDB will attempt to
+        start the replication up to 10 times (configurable under
+        <literal moreinfo="none">[replicator]</literal>, parameter
+        <literal moreinfo="none">max_replication_retry_count</literal>). If it fails on
+        the first attempt, it waits 5 seconds before doing a second
+        attempt. If the second attempt fails, it waits 10 seconds before
+        doing a third attempt. If the third attempt fails, it waits 20
+        seconds before doing a fourth attempt (each attempt doubles the
+        previous wait period). When an attempt fails, the Couch log will
+        show you something like:
+      </para>
+
+<programlisting format="linespecific">[error] [&lt;0.149.0&gt;] Error starting replication `67c1bb92010e7abe35d7d629635f18b6+create_target` (document `my_rep_2`): {db_not_found,&lt;&lt;"could not open http://myserver:5986/foo/"&gt;&gt;</programlisting>
+
+      <note>
+        <para>
+          The <literal moreinfo="none">_replication_state</literal> field is only set to
+          <literal moreinfo="none">error</literal> when all the attempts were
+          unsuccessful.
+        </para>
+      </note>
+
+      <para>
+        There are only 3 possible values for the
+        <literal moreinfo="none">_replication_state</literal> field:
+        <literal moreinfo="none">triggered</literal>, <literal moreinfo="none">completed</literal> and
+        <literal moreinfo="none">error</literal>. Continuous replications never get
+        their state set to <literal moreinfo="none">completed</literal>.
+      </para>
+
+    </section>
+
+    <section id="couchdb-single-replication-replicatordb-docsame">
+
+      <title>Documents describing the same replication</title>
+
+      <para>
+        Lets suppose 2 documents are added to the
+        <literal moreinfo="none">_replicator</literal> database in the following order:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "doc_A",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar"
+}</programlisting>
+
+      <para>
+        and
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "doc_B",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar"
+}</programlisting>
+
+      <para>
+        Both describe exactly the same replication (only their
+        <literal moreinfo="none">_ids</literal> differ). In this case document
+        <literal moreinfo="none">doc_A</literal> triggers the replication, getting
+        updated by CouchDB with the fields
+        <literal moreinfo="none">_replication_state</literal>,
+        <literal moreinfo="none">_replication_state_time</literal> and
+        <literal moreinfo="none">_replication_id</literal>, just like it was described
+        before. Document <literal moreinfo="none">doc_B</literal> however, is only
+        updated with one field, the <literal moreinfo="none">_replication_id</literal>
+        so it will look like this:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "doc_B",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar",
+    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280"
+}</programlisting>
+
+      <para>
+        While document <literal moreinfo="none">doc_A</literal> will look like this:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "doc_A",
+    "source":  "http://myserver.com:5984/foo",
+    "target":  "bar",
+    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+    "_replication_state":  "triggered",
+    "_replication_state_time":  1297974122
+}</programlisting>
+
+      <para>
+        Note that both document get exactly the same value for the
+        <literal moreinfo="none">_replication_id</literal> field. This way you can
+        identify which documents refer to the same replication - you can
+        for example define a view which maps replication IDs to document
+        IDs.
+      </para>
+
+    </section>
+
+    <section id="couchdb-single-replication-replicatordb-cancel">
+
+      <title>Canceling replications</title>
+
+      <para>
+        To cancel a replication simply <literal moreinfo="none">DELETE</literal> the
+        document which triggered the replication. The Couch log will
+        show you an entry like the following:
+      </para>
+
+<programlisting format="linespecific">[Thu, 17 Feb 2011 20:16:29 GMT] [info] [&lt;0.125.0&gt;] Stopped replication `c0ebe9256695ff083347cbf95f93e280+continuous+create_target` because replication document `doc_A` was deleted</programlisting>
+
+      <note>
+        <para>
+          You need to <literal moreinfo="none">DELETE</literal> the document that
+          triggered the replication. <literal moreinfo="none">DELETE</literal>ing
+          another document that describes the same replication but did
+          not trigger it, will not cancel the replication.
+        </para>
+      </note>
+
+    </section>
+
+    <section id="couchdb-single-replication-replicatordb-restart">
+
+      <title>Server restart</title>
+
+      <para>
+        When CouchDB is restarted, it checks its
+        <literal moreinfo="none">_replicator</literal> database and restarts any
+        replication that is described by a document that either has its
+        <literal moreinfo="none">_replication_state</literal> field set to
+        <literal moreinfo="none">triggered</literal> or it doesn't have yet the
+        <literal moreinfo="none">_replication_state</literal> field set.
+      </para>
+
+      <note>
+        <para>
+          Continuous replications always have a
+          <literal moreinfo="none">_replication_state</literal> field with the value
+          <literal moreinfo="none">triggered</literal>, therefore they're always
+          restarted when CouchDB is restarted.
+        </para>
+      </note>
+
+    </section>
+
+    <section id="couchdb-single-replication-replicatordb-changing">
+
+      <title>Changing the Replicator Database</title>
+
+      <para>
+        Imagine your replicator database (default name is _replicator)
+        has the two following documents that represent pull replications
+        from servers A and B:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "rep_from_A",
+    "source":  "http://aserver.com:5984/foo",
+    "target":  "foo_a",
+    "continuous":  true,
+    "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+    "_replication_state":  "triggered",
+    "_replication_state_time":  1297971311
+}
+{
+    "_id": "rep_from_B",
+    "source":  "http://bserver.com:5984/foo",
+    "target":  "foo_b",
+    "continuous":  true,
+    "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
+    "_replication_state":  "triggered",
+    "_replication_state_time":  1297974122
+}</programlisting>
+
+      <para>
+        Now without stopping and restarting CouchDB, you change the name
+        of the replicator database to
+        <literal moreinfo="none">another_replicator_db</literal>:
+      </para>
+
+<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"another_replicator_db"'
+"_replicator"</programlisting>
+
+      <para>
+        As soon as this is done, both pull replications defined before,
+        are stopped. This is explicitly mentioned in CouchDB's log:
+      </para>
+
+<programlisting format="linespecific">[Fri, 11 Mar 2011 07:44:20 GMT] [info] [&lt;0.104.0&gt;] Stopping all ongoing replications because the replicator database was deleted or changed
+[Fri, 11 Mar 2011 07:44:20 GMT] [info] [&lt;0.127.0&gt;] 127.0.0.1 - - PUT /_config/replicator/db 200</programlisting>
+
+      <para>
+        Imagine now you add a replication document to the new replicator
+        database named <literal moreinfo="none">another_replicator_db</literal>:
+      </para>
+
+<programlisting format="linespecific">{
+    "_id": "rep_from_X",
+    "source":  "http://xserver.com:5984/foo",
+    "target":  "foo_x",
+    "continuous":  true
+}</programlisting>
+
+      <para>
+        From now own you have a single replication going on in your
+        system: a pull replication pulling from server X. Now you change
+        back the replicator database to the original one
+        <literal moreinfo="none">_replicator</literal>:
+      </para>
+
+<programlisting format="linespecific">$ curl -X PUT http://localhost:5984/_config/replicator/db -d '"_replicator"'
+"another_replicator_db"</programlisting>
+
+      <para>
+        Immediately after this operation, the replication pulling from
+        server X will be stopped and the replications defined in the
+        _replicator database (pulling from servers A and B) will be
+        resumed.
+      </para>
+
+      <para>
+        Changing again the replicator database to
+        <literal moreinfo="none">another_replicator_db</literal> will stop the pull
+        replications pulling from servers A and B, and resume the pull
+        replication pulling from server X.
+      </para>
+
+    </section>
+
+    <section id="couchdb-single-replication-replicatordb-replicating">
+
+      <title>Replicating the replicator database</title>
+
+      <para>
+        Imagine you have in server C a replicator database with the two
+        following pull replication documents in it:
+      </para>
+
+<programlisting format="linespecific">{
+     "_id": "rep_from_A",
+     "source":  "http://aserver.com:5984/foo",
+     "target":  "foo_a",
+     "continuous":  true,
+     "_replication_id":  "c0ebe9256695ff083347cbf95f93e280",
+     "_replication_state":  "triggered",
+     "_replication_state_time":  1297971311
+}
+{
+     "_id": "rep_from_B",
+     "source":  "http://bserver.com:5984/foo",
+     "target":  "foo_b",
+     "continuous":  true,
+     "_replication_id":  "231bb3cf9d48314eaa8d48a9170570d1",
+     "_replication_state":  "triggered",
+     "_replication_state_time":  1297974122
+}</programlisting>
+
+      <para>
+        Now you would like to have the same pull replications going on
+        in server D, that is, you would like to have server D pull
+        replicating from servers A and B. You have two options:
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            Explicitly add two documents to server's D replicator
+            database
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            Replicate server's C replicator database into server's D
+            replicator database
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>
+        Both alternatives accomplish exactly the same goal.
+      </para>
+
+    </section>
+
+    <section id="couchdb-single-replication-replicatordb-delegations">
+
+      <title>Delegations</title>
+
+      <para>
+        Replication documents can have a custom
+        <literal moreinfo="none">user_ctx</literal> property. This property defines the
+        user context under which a replication runs. For the old way of
+        triggering replications (POSTing to
+        <literal moreinfo="none">/_replicate/</literal>), this property was not needed
+        (it didn't exist in fact) - this is because at the moment of
+        triggering the replication it has information about the
+        authenticated user. With the replicator database, since it's a
+        regular database, the information about the authenticated user
+        is only present at the moment the replication document is
+        written to the database - the replicator database implementation
+        is like a _changes feed consumer (with
+        <literal moreinfo="none">?include_docs=true</literal>) that reacts to what was
+        written to the replicator database - in fact this feature could
+        be implemented with an external script/program. This
+        implementation detail implies that for non admin users, a
+        <literal moreinfo="none">user_ctx</literal> property, containing the user's name
+        and a subset of his/her roles, must be defined in the
+        replication document. This is ensured by the document update
+        validation function present in the default design document of
+        the replicator database. This validation function also ensure
+        that a non admin user can set a user name property in the
+        <literal moreinfo="none">user_ctx</literal> property that doesn't match his/her
+        own name (same principle applies for the roles).
+      </para>
+
+      <para>
+        For admins, the <literal moreinfo="none">user_ctx</literal> property is
+        optional, and if it's missing it defaults to a user context with
+        name null and an empty list of roles - this mean design
+        documents will not be written to local targets. If writing
+        design documents to local targets is desired, the a user context
+        with the roles <literal moreinfo="none">_admin</literal> must be set explicitly.
+      </para>
+
+      <para>
+        Also, for admins the <literal moreinfo="none">user_ctx</literal> property can be
+        used to trigger a replication on behalf of another user. This is
+        the user context that will be passed to local target database
+        document validation functions.
+      </para>
+
+      <note>
+        <para>
+          The <literal moreinfo="none">user_ctx</literal> property only has effect for
+          local endpoints.
+        </para>
+      </note>
+
+      <para>
+        Example delegated replication document:
+      </para>
+
+<programlisting format="linespecific">{
+     "_id": "my_rep",
+     "source":  "http://bserver.com:5984/foo",
+     "target":  "bar",
+     "continuous":  true,
+     "user_ctx": {
+          "name": "joe",
+          "roles": ["erlanger", "researcher"]
+     }
+}</programlisting>
+
+      <para>
+        As stated before, for admins the user_ctx property is optional,
+        while for regular (non admin) users it's mandatory. When the
+        roles property of <literal moreinfo="none">user_ctx</literal> is missing, it
+        defaults to the empty list <literal moreinfo="none">[ ]</literal>.
+      </para>
+
+    </section>
+
+  </section>
+
+</chapter>
+
+
+
+  <chapter id="couchdb-api-basics">
+
+  <title>CouchDB API</title>
+
+  <para>
+    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.
+  </para>
+
+  <para>
+    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 <literal moreinfo="none">GET</literal> operation, while updates are
+    handled by either a <literal moreinfo="none">POST</literal> or
+    <literal moreinfo="none">PUT</literal> 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
+    <xref linkend="couchdb-api-introduction-requests"/>.
+  </para>
+
+  <para>
+    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 <xref linkend="couchdb-api-introduction-json"/>.
+  </para>
+
+  <para>
+    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
+    <xref linkend="couchdb-api-introduction-returncodes"/>.
+  </para>
+
+  <para>
+    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
+    <xref linkend="couchdb-api-overview"/>.
+  </para>
+
+  <section id="couchdb-api-introduction-requests">
+
+    <title>Request Format and Responses</title>
+
+    <para>
+      CouchDB supports the following HTTP request methods:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">GET</literal>
+        </para>
+
+        <para>
+          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.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">HEAD</literal>
+        </para>
+
+        <para>
+          The <literal moreinfo="none">HEAD</literal> method is used to get the HTTP
+          header of a <literal moreinfo="none">GET</literal> request without the body of
+          the response.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">POST</literal>
+        </para>
+
+        <para>
+          Upload data. Within CouchDB <literal moreinfo="none">POST</literal> is used to
+          set values, including uploading documents, setting document
+          values, and starting certain administration commands.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">PUT</literal>
+        </para>
+
+        <para>
+          Used to put a specified resource. In CouchDB
+          <literal moreinfo="none">PUT</literal> is used to create new objects,
+          including databases, documents, views and design documents.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">DELETE</literal>
+        </para>
+
+        <para>
+          Deletes the specified resource, including documents, views,
+          and design documents.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">COPY</literal>
+        </para>
+
+        <para>
+          A special method that can be used to copy documents and
+          objects.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      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:
+    </para>
+
+<programlisting format="linespecific">{
+    "error":"method_not_allowed",
+    "reason":"Only GET,HEAD allowed"
+}</programlisting>
+
+
+
+    <para>
+      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 <literal moreinfo="none">headers</literal>
+      block of the return object. For more information, see
+      <xref linkend="couchdb-api-functional"/>.
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-introduction-request-header">
+
+    <title>HTTP Headers</title>
+
+    <para>
+      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.
+    </para>
+
+    <section id="couchdb-api-introduction-request-header-request">
+
+      <title>Request Headers</title>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">Content-type</literal>
+          </para>
+
+          <para>
+            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 (<literal moreinfo="none">application/json</literal>). 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
+            (<literal moreinfo="none">application/octet-stream</literal>).
+          </para>
+
+          <para>
+            The use of the <literal moreinfo="none">Content-type</literal> on a request
+            is highly recommended.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">Accept</literal>
+          </para>
+
+          <para>
+            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.
+          </para>
+
+          <para>
+            For the majority of requests the definition should be for
+            JSON data (<literal moreinfo="none">application/json</literal>). For
+            attachments you can either specify the MIME type explicitly,
+            or use <literal moreinfo="none">*/*</literal> to specify that all file types
+            are supported. If the <literal moreinfo="none">Accept</literal> header is
+            not supplied, then the <literal moreinfo="none">*/*</literal> MIME type is
+            assumed (i.e. client accepts all formats).
+          </para>
+
+          <para>
+            The use of <literal moreinfo="none">Accept</literal> 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.
+          </para>
+
+          <para>
+            If you specify a data type using the
+            <literal moreinfo="none">Accept</literal> header, CouchDB will honor the
+            specified type in the <literal moreinfo="none">Content-type</literal> header
+            field returned. For example, if you explicitly request
+            <literal moreinfo="none">application/json</literal> in the
+            <literal moreinfo="none">Accept</literal> of a request, the returned HTTP
+            headers will use the value in the returned
+            <literal moreinfo="none">Content-type</literal> field.
+          </para>
+
+          <para>
+            For example, when sending a request without an explicit
+            <literal moreinfo="none">Accept</literal> header, or when specifying
+            <literal moreinfo="none">*/*</literal>:
+          </para>
+
+<programlisting format="linespecific">GET /recipes HTTP/1.1
+Host: couchdb:5984
+Accept: */*</programlisting>
+
+          <para>
+            The returned headers are:
+          </para>
+
+<programlisting format="linespecific">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</programlisting>
+
+          <para>
+            Note that the returned content type is
+            <literal moreinfo="none">text/plain</literal> even though the information
+            returned by the request is in JSON format.
+          </para>
+
+          <para>
+            Explicitly specifying the <literal moreinfo="none">Accept</literal> header:
+          </para>
+
+<programlisting format="linespecific">GET /recipes HTTP/1.1
+Host: couchdb:5984
+Accept: application/json</programlisting>
+
+          <para>
+            The headers returned include the
+            <literal moreinfo="none">application/json</literal> content type:
+          </para>
+
+<programlisting format="linespecific">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</programlisting>
+        </listitem>
+
+      </itemizedlist>
+
+    </section>
+
+    <section id="couchdb-api-introduction-request-header-response">
+
+      <title>Response Headers</title>
+
+      <para>
+        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.
+      </para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">Content-type</literal>
+          </para>
+
+          <para>
+            Specifies the MIME type of the returned data. For most
+            request, the returned MIME type is
+            <literal moreinfo="none">text/plain</literal>. All text is encoded in
+            Unicode (UTF-8), and this is explicitly stated in the
+            returned <literal moreinfo="none">Content-type</literal>, as
+            <literal moreinfo="none">text/plain;charset=utf-8</literal>.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">Cache-control</literal>
+          </para>
+
+          <para>
+            The cache control HTTP response header provides a suggestion
+            for client caching mechanisms on how to treat the returned
+            information. CouchDB typically returns the
+            <literal moreinfo="none">must-revalidate</literal>, 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.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">Content-length</literal>
+          </para>
+
+          <para>
+            The length (in bytes) of the returned content.
+          </para>
+        </listitem>
+
+        <listitem>
+          <para>
+            <literal moreinfo="none">Etag</literal>
+          </para>
+
+          <para>
+            The <literal moreinfo="none">Etag</literal> HTTP header field is used to
+            show the revision for a document.
+          </para>
+        </listitem>
+
+      </itemizedlist>
+
+    </section>
+
+  </section>
+
+  <section id="couchdb-api-introduction-json">
+
+    <title>JSON Basics</title>
+
+    <para>
+      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.
+    </para>
+
+    <para>
+      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.
+    </para>
+
+    <para>
+      JSON supports the same basic types as supported by JavaScript,
+      these are:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Number (either integer or floating-point).
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          String; this should be enclosed by double-quotes and supports
+          Unicode characters and backslash escaping. For example:
+        </para>
+
+<programlisting format="linespecific">"A String"</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
+          Boolean - a <literal moreinfo="none">true</literal> or
+          <literal moreinfo="none">false</literal> value. You can use these strings
+          directly. For example:
+        </para>
+
+<programlisting format="linespecific">{ "value": true}</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
+          Array - a list of values enclosed in square brackets. For
+          example:
+        </para>
+
+<programlisting format="linespecific">["one", "two", "three"]</programlisting>
+      </listitem>
+
+      <listitem>
+        <para>
+          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 supported JSON values. For example:
+        </para>
+
+<programlisting format="linespecific">{
+   "servings" : 4,
+   "subtitle" : "Easy to make in advance, and then cook when ready",
+   "cooktime" : 60,
+   "title" : "Chicken Coriander"
+}</programlisting>
+
+        <para>
+          In CouchDB, the JSON object is used to represent a variety of
+          structures, including the main CouchDB document.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Parsing JSON into a JavaScript object is supported through the
+      <literal moreinfo="none">eval()</literal> function in JavaScript, or through
+      various libraries that will perform the parsing of the content
+      into a JavaScript object for you. Libraries for parsing and
+      generating JSON are available in many languages, including Perl,
+      Python, Ruby, Erlang and others.
+    </para>
+
+    <warning>
+      <para>
+        Care should be taken to ensure that your JSON structures are
+        valid, invalid structures will cause CouchDB to return an HTTP
+        status code of 500 (server error). See
+        <xref linkend="couchdb-api-introduction-returncode-500"/>
+        .
+      </para>
+    </warning>
+
+  </section>
+
+  <section id="couchdb-api-introduction-returncodes">
+
+    <title>HTTP Status Codes</title>
+
+    <para>
+      With the interface to CouchDB working through HTTP, error codes
+      and statuses are reported using a combination of the HTTP status
+      code number, and corresponding data in the body of the response
+      data.
+    </para>
+
+    <para>
+      A list of the error codes returned by CouchDB, and generic
+      descriptions of the related errors are provided below. The meaning
+      of different status codes for specific request types are provided
+      in the corresponding API call reference.
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-200">
+          <literal moreinfo="none">200 - OK</literal>
+        </para>
+
+        <para>
+          Request completed successfully.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-201">
+          <literal moreinfo="none">201 - Created</literal>
+        </para>
+
+        <para>
+          Document created successfully.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-202">
+          <literal moreinfo="none">202 - Accepted</literal>
+        </para>
+
+        <para>
+          Request has been accepted, but the corresponding operation may
+          not have completed. This is used for background operations,
+          such as database compaction.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-304">
+          <literal moreinfo="none">304 - Not Modified</literal>
+        </para>
+
+        <para>
+          The additional content requested has not been modified. This
+          is used with the ETag system to identify the version of
+          information returned.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-400">
+          <literal moreinfo="none">400 - Bad Request</literal>
+        </para>
+
+        <para>
+          Bad request structure. The error can indicate an error with
+          the request URL, path or headers. Differences in the supplied
+          MD5 hash and content also trigger this error, as this may
+          indicate message corruption.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-401">
+          <literal moreinfo="none">401 - Unauthorized</literal>
+        </para>
+
+        <para>
+          The item requested was not available using the supplied
+          authorization, or authorization was not supplied.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-403">
+          <literal moreinfo="none">403 - Forbidden</literal>
+        </para>
+
+        <para>
+          The requested item or operation is forbidden.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-404">
+          <literal moreinfo="none">404 - Not Found</literal>
+        </para>
+
+        <para>
+          The requested content could not be found. The content will
+          include further information, as a JSON object, if available.
+          The structure will contain two keys, <literal moreinfo="none">error</literal>
+          and <literal moreinfo="none">reason</literal>. For example:
+        </para>
+
+<programlisting format="linespecific">{"error":"not_found","reason":"no_db_file"}</programlisting>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-405">
+          <literal moreinfo="none">405 - Resource Not Allowed</literal>
+        </para>
+
+        <para>
+          A request was made using an invalid HTTP request type for the
+          URL requested. For example, you have requested a
+          <literal moreinfo="none">PUT</literal> when a <literal moreinfo="none">POST</literal> is
+          required. Errors of this type can also triggered by invalid
+          URL strings.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-406">
+          <literal moreinfo="none">406 - Not Acceptable</literal>
+        </para>
+
+        <para>
+          The requested content type is not supported by the server.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-409">
+          <literal moreinfo="none">409 - Conflict</literal>
+        </para>
+
+        <para>
+          Request resulted in an update conflict.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-412">
+          <literal moreinfo="none">412 - Precondition Failed</literal>
+        </para>
+
+        <para>
+          The request headers from the client and the capabilities of
+          the server do not match.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-415">
+          <literal moreinfo="none">415 - Bad Content Type</literal>
+        </para>
+
+        <para>
+          The content types supported, and the content type of the
+          information being requested or submitted indicate that the
+          content type is not supported.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-416">
+          <literal moreinfo="none">416 - Requested Range Not Satisfiable</literal>
+        </para>
+
+        <para>
+          The range specified in the request header cannot be satisfied
+          by the server.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-417">
+          <literal moreinfo="none">417 - Expectation Failed</literal>
+        </para>
+
+        <para>
+          When sending documents in bulk, the bulk load operation
+          failed.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para id="couchdb-api-introduction-returncode-500" xreflabel="HTTP               Status Code 500">
+          <literal moreinfo="none">500 - Internal Server Error</literal>
+        </para>
+
+        <para>
+          The request was invalid, either because the supplied JSON was
+          invalid, or invalid information was supplied as part of the
+          request.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+  </section>
+
+  <section id="couchdb-api-overview">
+
+    <title>CouchDB API Overview</title>
+
+    <para>
+      The components of the API URL path help determine the part of the
+      CouchDB server that is being accessed. The result is the structure
+      of the URL request both identifies and effectively describes the
+      area of the database you are accessing.
+    </para>
+
+    <para>
+      As with all URLs, the individual components are separated by a
+      forward slash.
+    </para>
+
+    <para>
+      As a general rule, URL components and JSON fields starting with
+      the <literal moreinfo="none">_</literal> (underscore) character represent a
+      special component or entity within the server or returned object.
+      For example, the URL fragment <literal moreinfo="none">/_all_dbs</literal> gets a
+      list of all of the databases in a CouchDB instance.
+    </para>
+
+    <para>
+      The remainder of the URL API structure can be divided up according
+      to the URL structure. The different sections are divided as
+      follows:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">/db</literal>
+        </para>
+
+        <para>
+          Database methods, related to adding, updating or deleting
+          databases, and setting database parameters and operations. For
+          more detailed information, see
+          <xref linkend="couchdb-api-db"/> .
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">/db/doc</literal>
+        </para>
+
+        <para>
+          Document methods, those that create, store, update or delete
+          CouchDB documents and their attachments. For more information,
+          see <xref linkend="couchdb-api-dbdoc"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">/db/_local/local-doc</literal>
+        </para>
+
+        <para>
+          Document methods, those that create, store, update or delete
+          CouchDB documents only within the local database. Local
+          documents are not synchronized with other databases. For more
+          information, see
+          <xref linkend="couchdb-api-localdb"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">/db/_design/design-doc</literal>
+        </para>
+
+        <para>
+          Design documents provide the methods and structure for
+          recovering information from a CouchDB database in the form of
+          views, shows and lists. For more information, see
+          <xref linkend="couchdb-api-design"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">/_special</literal>
+        </para>
+
+        <para>
+          Special methods that obtain or set information about the
+          CouchDB instance, including methods for configuring
+          replication, accessing the logs, and generate Universally
+          Unique IDs (UUIDs). For more information, see
+          <xref linkend="couchdb-api-misc"/>.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          <literal moreinfo="none">/_config</literal>
+        </para>
+
+        <para>
+          Methods for getting, and settings, CouchDB configuration
+          parameters. For more information, see
+          <xref linkend="couchdb-api-misc"/>.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+
+
+  </section>
+
+</chapter>
+
+  <chapter id="couchdb-api-db">
+
+  <title>CouchDB API Server Database Methods</title>
+
+  <para>
+    The Database methods provide an interface to an entire database
+    withing CouchDB. These are database, rather than document, level
+    requests.
+  </para>
+
+  <para>
+    A list of the available methods and URL paths are provided below:
+  </para>
+
+  <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<table id="table-couchdb-api-db-summary"><title>Database API Calls</title><tgroup cols="3"><colspec colname="method"/><colspec colname="path"/><colspec colname="desc"/><thead><row><entry>Method</entry><entry>Path</entry><entry>Description</entry></row></thead><tbody><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_get">
+ Returns database information
+ </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_put">
+ Create a new database
+ </link></entry></row><row><entry><literal moreinfo="none">DELETE</literal></entry><entry><literal moreinfo="none">/db</literal></entry><entry><link linkend="couchdb-api-db_db_delete">
+ Delete an existing database
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_get">
+ Returns a built-in view of all documents in this database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_all_docs</literal></entry><entry><link linkend="couchdb-api-db_db-all-docs_post">
+ Returns certain rows from the built-in view of all documents
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_bulk_docs</literal></entry><entry><link linkend="couchdb-api-db_db-bulk-docs_post">
+ Insert multiple documents in to the database in a single request
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_changes</literal></entry><entry><link linkend="couchdb-api-db_db-changes_get">
+ Returns changes for the given database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact</literal></entry><entry><link linkend="couchdb-api-db_db-compact_post">
+ Starts a compaction for the database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_compact/design-doc</literal></entry><entry><link linkend="couchdb-api-db_db-compact-design-doc_post">
+ Starts a compaction for all the views in the selected design
+ document
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_ensure_full_commit</literal></entry><entry><link linkend="couchdb-api-db_db-ensure-full-commit_post">
+ Makes sure all uncommitted changes are written and synchronized
+ to the disk
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_missing_revs</literal></entry><entry><link linkend="couchdb-api-db_db-missing-revs_post">
+ Given a list of document revisions, returns the document
+ revisions that do not exist in the database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_purge</literal></entry><entry><link linkend="couchdb-api-db_db-purge_post">
+ Purge some historical documents entirely from database history
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_revs_diff</literal></entry><entry><link linkend="couchdb-api-db_db-revs-diff_post">
+ Given a list of document revisions, returns differences between
+ the given revisions and ones that are in the database
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_get">
+ Gets the limit of historical revisions to store for a single
+ document in the database
+ </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_revs_limit</literal></entry><entry><link linkend="couchdb-api-db_db-revs-limit_put">
+ Sets the limit of historical revisions to store for a single
+ document in the database
+ </link></entry></row><row><entry><literal moreinfo="none">GET</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_get">
+ Returns the special security object for the database
+ </link></entry></row><row><entry><literal moreinfo="none">PUT</literal></entry><entry><literal moreinfo="none">/db/_security</literal></entry><entry><link linkend="couchdb-api-db_db-security_put">
+ Sets the special security object for the database
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_temp_view</literal></entry><entry><link linkend="couchdb-api-db_db-temp-view_post">
+ Execute a given view function for all documents and return the
+ result
+ </link></entry></row><row><entry><literal moreinfo="none">POST</literal></entry><entry><literal moreinfo="none">/db/_view_cleanup</literal></entry><entry><link linkend="couchdb-api-db_db-view-cleanup_post">
+ Removes view files that are not used by any design document
+ </link></entry></row></tbody></tgroup></table>
+
+  <para>
+    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
+    <literal moreinfo="none">recipes</literal>, you would use the HTTP request:
+  </para>
+
+<programlisting format="linespecific">GET /recipes</programlisting>
+
+  <para>
+    For clarity, the form below is used in the URL paths:
+  </para>
+
+<programlisting format="linespecific">GET /db</programlisting>
+
+  <para>
+    Where <literal moreinfo="none">db</literal> is the name of any database.
+  </para>
+
+  <section id="couchdb-api-db_db_get">
+
+    <title><literal moreinfo="none">GET /db</literal></title>
+
+    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<informaltable><textobject><phrase>URL API GET /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">GET /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo">
+ None
+ </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo">
+ Information about the database in JSON format
+ </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>404</entry><entry namest="info" nameend="addinfo">
+ The requested content could not be found. The returned content
+ will include further information, as a JSON object, if available.
+ </entry></row></tbody></tgroup></informaltable>
+
+    <para>
+      Gets information about the specified database. For example, to
+      retrieve the information for the database
+      <literal moreinfo="none">recipe</literal>:
+    </para>
+
+<programlisting role="httprequest" format="linespecific">GET http://couchdb:5984/recipes
+Accept: application/json</programlisting>
+
+    <para>
+      The JSON response contains meta information about the database. A
+      sample of the JSON returned for an empty database is provided
+      below:
+    </para>
+
+<programlisting role="httpresponse" format="linespecific">{
+   "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
+}</programlisting>
+
+    <para>
+      The elements of the returned structure are shown in the table
+      below:
+    </para>
+
+    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/JSON/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//json/json.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<table id="table-couchdb-api-db-json-db-info" class="jsonstructure"><title>
+ CouchDB database information object
+ </title><tgroup cols="2"><colspec colname="item" colwidth="30*"/><colspec colname="desc" colwidth="70*"/><tbody><row><entry><emphasis role="bold">Field</emphasis></entry><entry><emphasis role="bold">Description</emphasis></entry></row><row><entry><literal moreinfo="none">committed_update_seq</literal>  </entry><entry>
+ The number of committed update.
+ </entry></row><row><entry><literal moreinfo="none">compact_running</literal>  </entry><entry>
+ Set to true if the database compaction routine is operating on
+ this database.
+ </entry></row><row><entry><literal moreinfo="none">db_name</literal>  </entry><entry>
+ The name of the database.
+ </entry></row><row><entry><literal moreinfo="none">disk_format_version</literal>  </entry><entry>
+ The version of the physical format used for the data when it is
+ stored on disk.
+ </entry></row><row><entry><literal moreinfo="none">disk_size</literal>  </entry><entry>
+ Size in bytes of the data as stored on the disk. Views indexes
+ are not included in the calculation.
+ </entry></row><row><entry><literal moreinfo="none">doc_count</literal>  </entry><entry>
+ A count of the documents in the specified database.
+ </entry></row><row><entry><literal moreinfo="none">doc_del_count</literal>  </entry><entry>
+ Number of deleted documents
+ </entry></row><row><entry><literal moreinfo="none">instance_start_time</literal>  </entry><entry>
+ Timestamp of when the database was created, expressed in
+ milliseconds since the epoch.
+ </entry></row><row><entry><literal moreinfo="none">purge_seq</literal>  </entry><entry>
+ The number of purge operations on the database.
+ </entry></row><row><entry><literal moreinfo="none">update_seq</literal>  </entry><entry>
+ The current number of updates to the database.
+ </entry></row></tbody></tgroup></table>
+
+  </section>
+
+  <section id="couchdb-api-db_db_put">
+
+    <title><literal moreinfo="none">PUT /db</literal></title>
+
+    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs.pm"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/JSON.pm"/>
+<informaltable><textobject><phrase>URL API PUT /db</phrase></textobject><tgroup cols="3"><colspec colname="field"/><colspec colname="info"/><colspec colname="addinfo"/><tbody><row><entry><emphasis role="bold">Method</emphasis></entry><entry namest="info" nameend="addinfo"><literal moreinfo="none">PUT /db</literal></entry></row><row><entry><emphasis role="bold">Request</emphasis></entry><entry namest="info" nameend="addinfo">
+ None
+ </entry></row><row><entry><emphasis role="bold">Response</emphasis></entry><entry namest="info" nameend="addinfo">
+ JSON success statement
+ </entry></row><row><entry><emphasis role="bold">Admin Privileges Required</emphasis></entry><entry namest="info" nameend="addinfo">no</entry></row><row><entry namest="field" nameend="addinfo"><emphasis role="bold">Return Codes</emphasis></entry></row><row><entry>400</entry><entry namest="info" nameend="addinfo">
+ Invalid database name
+ </entry></row><row><entry>412</entry><entry namest="info" nameend="addinfo">
+ Database already exists
+ </entry></row></tbody></tgroup></informaltable>
+
+    <para>
+      Creates a new database. The database name must be composed of one
+      or more of the following characters:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Lowercase characters (<literal moreinfo="none">a-z</literal>)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Name must begin with a lowercase letter
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Digits (<literal moreinfo="none">0-9</literal>)
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Any of the characters <literal moreinfo="none">_</literal>,
+          <literal moreinfo="none">$</literal>, <literal moreinfo="none">(</literal>,
+          <literal moreinfo="none">)</literal>, <literal moreinfo="none">+</literal>,
+          <literal moreinfo="none">-</literal>, and <literal moreinfo="none">/</literal>.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Trying to create a database that does not meet these requirements
+      will return an error quoting these restrictions.
+    </para>
+
+    <para>
+      To create the database <literal moreinfo="none">recipes</literal>:
+    </para>
+
+<programlisting format="linespecific">PUT http://couchdb:5984/recipes
+Content-Type: application/json</programlisting>
+
+    <para>
+      The returned content contains the JSON status:
+    </para>
+
+<programlisting format="linespecific">{
+   "ok" : true
+}</programlisting>
+
+    <para>
+      Anything should be treated as an error, and the problem should be
+      taken form the HTTP response code.
+    </para>
+
+  </section>
+
+  <section id="couchdb-api-db_db_delete">
+
+    <title><literal moreinfo="none">DELETE /db</literal></title>
+
+    <remark role="dependency-meta" condition="../DocKit/bin/CouchDocs/URLAPI/Parser.pm"/>
+<remark role="dependency-meta" condition="../metadocs//urlapi/couchdb.xml"/>
+<remark role="dependency-tool" condition="../DocKit/bin/CouchDocs/URLAPI.pm"/>
+<rem

<TRUNCATED>

Mime
View raw message