Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id C07C6DF99 for ; Wed, 12 Dec 2012 20:35:08 +0000 (UTC) Received: (qmail 46436 invoked by uid 500); 12 Dec 2012 20:35:07 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 46325 invoked by uid 500); 12 Dec 2012 20:35:07 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 46191 invoked by uid 99); 12 Dec 2012 20:35:07 -0000 Received: from tyr.zones.apache.org (HELO tyr.zones.apache.org) (140.211.11.114) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 12 Dec 2012 20:35:07 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id 5BE9181B9F3; Wed, 12 Dec 2012 20:35:07 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: dch@apache.org To: commits@couchdb.apache.org X-Mailer: ASF-Git Admin Mailer Subject: [4/34] git commit: Transmogrify Couchbase XML to .rst and support Sphinx Message-Id: <20121212203507.5BE9181B9F3@tyr.zones.apache.org> Date: Wed, 12 Dec 2012 20:35:07 +0000 (UTC) Transmogrify Couchbase XML to .rst and support Sphinx Authors: Alexander Shorin Dave Cottlehuber Dirkjan Ochtman Robert Newson Tady Walsh for the spiffy logo Robert Newson: - hear no eval, see no eval, speak no eval - fix minor niggles Dave Cottlehuber: - Remove vestiges of svn URLs in comments - Add browser EventSource protocol support for changes feed - Add all UUID algorithms including new utc+suffix-based UUID scheme - refactor 1.1.x features and other into 1.2.0 docs - remove manual.rst & release.rst files, only used during migration - prepare conf.py to be run from share/Makefile similar to: sphinx-build -a -E -W -n \ -D version='$ver' \ -D release='$ver-git-sha' \ -D project='Apache CouchDB' \ -D copyright='$year, Apache Software Foundation' \ -c `pwd` \ -d /tmp/ \ rst/ \ - set sphinx config: - update copyright & project - set default syntax highlighting to JSON - output docs to share/docs/manual - move into share/docs/rst - move old 1.1 .rst updates into main area - add release.rst for future release notes - swap specific versions and releases for sphinx variables Transmogrify XML to rst using pandoc 1.9.4.2: pandoc --smart --preserve-tabs --normalize --reference-links --chapters \ --number-sections --standalone --from docbook --to rst --output rst/manual.rst couchdb-manual-1.1/*.xml pandoc --smart --preserve-tabs --normalize --reference-links --chapters \ --number-sections --standalone --from docbook --to rst --output rst/release.rst couchdb-release-1.1/*.xml rm -rf share/docs Alexander Shorin: - Convert CHANGES file to rst, update information about 1.3.0 release. - Actual till #fb670f5712 commit at 2012-12-02. - Enable extlink extension. Setup extlink to CouchDB JIRA and Apache Git commits. - Enable sections enumeration. Looks nicer for further referencing. - Fix copy-paste typo, remove changes history for request object - Add article about queryservers: JavaScript and Erlang one - Complete article about how to write design documents - Shift filter functions from changes and point to ddocs - Add response object and view head info structure - Add query server and CommonJS - Fix markup of errors section - Fix caution blocks - Add back JSON structure reference - Clarify what kind of contents should go in views - Add back configuration option reference - Add TODO.txt for future reference - Add tables to start of API reference sections (except for design docs) - Fix indentation - Add syntax highlighting - Add to-do statements - Fix weird `_` escaping - Wrap statements - Add method descriptions - Clean up tables - Add missed `PUT /db/_revs_limit` description Dirkjan Ochtman: - Move .rst files into Sphinx Layout - Move rst files and copy images into a Sphinx project - Split manual & release docs into smaller pieces - Update version numbers - Move API docs into separate directory Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/84226656 Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/84226656 Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/84226656 Branch: refs/heads/master Commit: 84226656ab3fad6f95029aad993be9f5ec4f1794 Parents: ffca957 Author: Dave Cottlehuber Authored: Mon Dec 3 09:30:25 2012 +0100 Committer: Dave Cottlehuber Committed: Tue Dec 11 14:10:52 2012 +0100 ---------------------------------------------------------------------- share/doc/images/epub-icon.png | Bin 0 -> 19185 bytes share/doc/images/favicon.ico | Bin 0 -> 9326 bytes share/doc/images/futon-createdb.png | Bin 0 -> 76194 bytes share/doc/images/futon-editdoc.png | Bin 0 -> 64369 bytes share/doc/images/futon-editeddoc.png | Bin 0 -> 69595 bytes share/doc/images/futon-overview.png | Bin 0 -> 63039 bytes share/doc/images/futon-replform.png | Bin 0 -> 68068 bytes share/doc/images/logo.png | Bin 0 -> 13195 bytes share/doc/src/api-basics.rst | 459 + share/doc/src/api/authn.rst | 41 + share/doc/src/api/configuration.rst | 297 + share/doc/src/api/database.rst | 1463 +++ share/doc/src/api/dbmaint.rst | 15 + share/doc/src/api/design.rst | 1264 ++ share/doc/src/api/documents.rst | 973 ++ share/doc/src/api/local.rst | 169 + share/doc/src/api/misc.rst | 805 ++ share/doc/src/api/reference.rst | 28 + share/doc/src/changelog.rst | 1175 ++ share/doc/src/changes.rst | 214 + share/doc/src/commonjs.rst | 56 + share/doc/src/conf.py | 88 + share/doc/src/config_reference.rst | 288 + share/doc/src/configuring.rst | 148 + share/doc/src/ddocs.rst | 724 ++ share/doc/src/errors.rst | 37 + share/doc/src/http-proxying.rst | 94 + share/doc/src/index.rst | 52 + share/doc/src/intro.rst | 309 + share/doc/src/json-structure.rst | 658 + share/doc/src/os-daemons.rst | 50 + share/doc/src/pretty_urls.rst | 136 + share/doc/src/query-servers.rst | 481 + share/doc/src/range.rst | 72 + share/doc/src/release.rst | 47 + share/doc/src/replication.rst | 383 + share/doc/src/ssl.rst | 109 + .../couchdb-api-auth-metasrc.xml | 36 - .../couchdb-api-config-metasrc.xml | 359 - .../couchdb-manual-1.1/couchdb-api-db-metasrc.xml | 1828 --- .../couchdb-api-dbdoc-metasrc.xml | 1016 -- .../couchdb-api-design-metasrc.xml | 1462 --- .../couchdb-api-introduction.xml | 851 -- .../couchdb-api-json-metasrc.xml | 43 - .../couchdb-api-localdb-metasrc.xml | 186 - .../couchdb-api-misc-metasrc.xml | 1357 --- .../couchdb-manual-1.1/couchdb-changes-metasrc.xml | 67 - .../couchdb-config-options-metasrc.xml | 393 - .../couchdb-manual-1.1/couchdb-configuration.xml | 328 - share/docs/couchdb-manual-1.1/couchdb-dbmaint.xml | 15 - share/docs/couchdb-manual-1.1/couchdb-features.xml | 301 - .../couchdb-manual-1.1/couchdb-introduction.xml | 578 - .../couchdb-manual-1.1/couchdb-manual-ready.xml | 9409 --------------- share/docs/couchdb-manual-1.1/couchdb-manual.xml | 65 - .../couchdb-manual-1.1/couchdb-replication.xml | 554 - .../couchdb-single-troubleshooting.xml | 35 - share/docs/couchdb-manual-1.1/couchdb-views.xml | 15 - .../metadoc-couchdb-api-auth.xml | 40 - .../metadoc-couchdb-api-config.xml | 348 - .../couchdb-manual-1.1/metadoc-couchdb-api-db.xml | 1937 --- .../metadoc-couchdb-api-dbdoc.xml | 1091 -- .../metadoc-couchdb-api-design.xml | 1543 --- .../metadoc-couchdb-api-json.xml | 347 - .../metadoc-couchdb-api-localdb.xml | 188 - .../metadoc-couchdb-api-misc.xml | 1412 --- .../metadoc-couchdb-config-options.xml | 413 - .../couchdb-release-1.1-ready.xml | 1154 -- .../couchdb-release-1.1/couchdb-release-1.1.xml | 1243 -- 68 files changed, 10635 insertions(+), 28614 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/epub-icon.png ---------------------------------------------------------------------- diff --git a/share/doc/images/epub-icon.png b/share/doc/images/epub-icon.png new file mode 100644 index 0000000..3fda935 Binary files /dev/null and b/share/doc/images/epub-icon.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/favicon.ico ---------------------------------------------------------------------- diff --git a/share/doc/images/favicon.ico b/share/doc/images/favicon.ico new file mode 100644 index 0000000..34bfaa8 Binary files /dev/null and b/share/doc/images/favicon.ico differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/futon-createdb.png ---------------------------------------------------------------------- diff --git a/share/doc/images/futon-createdb.png b/share/doc/images/futon-createdb.png new file mode 100644 index 0000000..c8c1b9d Binary files /dev/null and b/share/doc/images/futon-createdb.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/futon-editdoc.png ---------------------------------------------------------------------- diff --git a/share/doc/images/futon-editdoc.png b/share/doc/images/futon-editdoc.png new file mode 100644 index 0000000..6802c2c Binary files /dev/null and b/share/doc/images/futon-editdoc.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/futon-editeddoc.png ---------------------------------------------------------------------- diff --git a/share/doc/images/futon-editeddoc.png b/share/doc/images/futon-editeddoc.png new file mode 100644 index 0000000..5c8b549 Binary files /dev/null and b/share/doc/images/futon-editeddoc.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/futon-overview.png ---------------------------------------------------------------------- diff --git a/share/doc/images/futon-overview.png b/share/doc/images/futon-overview.png new file mode 100644 index 0000000..d1eac6e Binary files /dev/null and b/share/doc/images/futon-overview.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/futon-replform.png ---------------------------------------------------------------------- diff --git a/share/doc/images/futon-replform.png b/share/doc/images/futon-replform.png new file mode 100644 index 0000000..d904f0d Binary files /dev/null and b/share/doc/images/futon-replform.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/images/logo.png ---------------------------------------------------------------------- diff --git a/share/doc/images/logo.png b/share/doc/images/logo.png new file mode 100644 index 0000000..9eac89e Binary files /dev/null and b/share/doc/images/logo.png differ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/api-basics.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/api-basics.rst b/share/doc/src/api-basics.rst new file mode 100644 index 0000000..97ea70c --- /dev/null +++ b/share/doc/src/api-basics.rst @@ -0,0 +1,459 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-basics: + +=========== +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 :ref:`api-format`. + +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 +:ref:`json`. + +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 :ref:`errors`. + +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 +:ref:`api-overview`. + +.. _api-format: + +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: + +.. code-block:: javascript + + { + "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. + +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 ``*/*``: + + .. code-block:: http + + GET /recipes HTTP/1.1 + Host: couchdb:5984 + Accept: */* + + The returned headers are: + + .. code-block:: http + + 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: + + .. code-block:: http + + GET /recipes HTTP/1.1 + Host: couchdb:5984 + Accept: application/json + + The headers returned include the ``application/json`` content type: + + .. code-block:: http + + Server: CouchDB/|version| (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, or a view. + + 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. + + Each ``_view`` URL has its 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). + +.. _json: + +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: + + .. code-block:: javascript + + "A String" + +- Boolean - a ``true`` or ``false`` value. You can use these strings + directly. For example: + + .. code-block:: javascript + + { "value": true} + +- Array - a list of values enclosed in square brackets. For example: + + .. code-block:: javascript + + ["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 + supported JSON values. For example: + + .. code-block:: javascript + + { + "servings" : 4, + "subtitle" : "Easy to make in advance, and then cook when ready", + "cooktime" : 60, + "title" : "Chicken Coriander" + } + + + In CouchDB, the JSON object is used to represent a variety of + structures, including the main CouchDB document. + +Parsing JSON into a JavaScript object is supported through the +``JSON.parse()`` 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. + +.. warning:: + 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). + +.. _errors: + +HTTP Status Codes +================= + +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. + +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. + +- ``200 - OK`` + + Request completed successfully. + +- ``201 - Created`` + + Document created successfully. + +- ``202 - Accepted`` + + Request has been accepted, but the corresponding operation may not + have completed. This is used for background operations, such as + database compaction. + +- ``304 - Not Modified`` + + The additional content requested has not been modified. This is used + with the ETag system to identify the version of information returned. + +- ``400 - Bad Request`` + + 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. + +- ``401 - Unauthorized`` + + The item requested was not available using the supplied + authorization, or authorization was not supplied. + +- ``403 - Forbidden`` + + The requested item or operation is forbidden. + +- ``404 - Not Found`` + + 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, ``error`` and ``reason``. For example: + + .. code-block:: javascript + + {"error":"not_found","reason":"no_db_file"} + +- ``405 - Resource Not Allowed`` + + A request was made using an invalid HTTP request type for the URL + requested. For example, you have requested a ``PUT`` when a ``POST`` + is required. Errors of this type can also triggered by invalid URL + strings. + +- ``406 - Not Acceptable`` + + The requested content type is not supported by the server. + +- ``409 - Conflict`` + + Request resulted in an update conflict. + +- ``412 - Precondition Failed`` + + The request headers from the client and the capabilities of the + server do not match. + +- ``415 - Bad Content Type`` + + The content types supported, and the content type of the information + being requested or submitted indicate that the content type is not + supported. + +- ``416 - Requested Range Not Satisfiable`` + + The range specified in the request header cannot be satisfied by the + server. + +- ``417 - Expectation Failed`` + + When sending documents in bulk, the bulk load operation failed. + +- ``500 - Internal Server Error`` + + The request was invalid, either because the supplied JSON was + invalid, or invalid information was supplied as part of the request. + +.. _api-overview: + +CouchDB API Overview +==================== + +The components of the API URL path help determine the part of the +CouchDB server that is being accessed. The result is the structure of +the URL request both identifies and effectively describes the area of +the database you are accessing. + +As with all URLs, the individual components are separated by a forward +slash. + +As a general rule, URL components and JSON fields starting with the +``_`` (underscore) character represent a special component or entity +within the server or returned object. For example, the URL fragment +``/_all_dbs`` gets a list of all of the databases in a CouchDB instance. + +The remainder of the URL API structure can be divided up according to +the URL structure. The different sections are divided as follows: + +- ``/db`` + + Database methods, related to adding, updating or deleting databases, + and setting database parameters and operations. For more detailed + information, see :ref:`api-db`. + +- ``/db/doc`` + + Document methods, those that create, store, update or delete CouchDB + documents and their attachments. For more information, see :ref:`api-doc`. + +- ``/db/_local/local-doc`` + + 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 + :ref:`api-local`. + +- ``/db/_design/design-doc`` + + 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 :ref:`api-design`. + +- ``/_special`` + + 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 :ref:`api-misc`. + +- ``/_config`` + + Methods for getting, and settings, CouchDB configuration parameters. + For more information, see :ref:`api-config`. http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/api/authn.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/api/authn.rst b/share/doc/src/api/authn.rst new file mode 100644 index 0000000..bac198b --- /dev/null +++ b/share/doc/src/api/authn.rst @@ -0,0 +1,41 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +====================== +Authentication Methods +====================== + +.. todo:: 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: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | /_oauth/access_token | TBC | ++--------+-------------------------+-------------------------------------------+ +| GET | /_oauth/authorize | TBC | ++--------+-------------------------+-------------------------------------------+ +| POST | /_oauth/authorize | TBC | ++--------+-------------------------+-------------------------------------------+ +| GET | /_oauth/request_token | TBC | ++--------+-------------------------+-------------------------------------------+ +| GET | /_session | Returns cookie based login user | +| | | information | ++--------+-------------------------+-------------------------------------------+ +| POST | /_session | Do cookie based user login | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /_session | Logout cookie based user | ++--------+-------------------------+-------------------------------------------+ http://git-wip-us.apache.org/repos/asf/couchdb/blob/84226656/share/doc/src/api/configuration.rst ---------------------------------------------------------------------- diff --git a/share/doc/src/api/configuration.rst b/share/doc/src/api/configuration.rst new file mode 100644 index 0000000..6c2c588 --- /dev/null +++ b/share/doc/src/api/configuration.rst @@ -0,0 +1,297 @@ +.. Licensed under the Apache License, Version 2.0 (the "License"); you may not +.. use this file except in compliance with the License. You may obtain a copy of +.. the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +.. License for the specific language governing permissions and limitations under +.. the License. + +.. _api-config: + +===================== +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: + ++--------+-------------------------+-------------------------------------------+ +| Method | Path | Description | ++========+=========================+===========================================+ +| GET | /_config | Obtain a list of the entire server | +| | | configuration | ++--------+-------------------------+-------------------------------------------+ +| GET | /_config/section | Get all the configuration values for the | +| | | specified section | ++--------+-------------------------+-------------------------------------------+ +| GET | /_config/section/key | Get a specific section/configuration value| ++--------+-------------------------+-------------------------------------------+ +| PUT | /_config/section/key | Set the specified configuration value | ++--------+-------------------------+-------------------------------------------+ +| DELETE | /_config/section/key | Delete the current setting | ++--------+-------------------------+-------------------------------------------+ + +``GET /_config`` +================ + +* **Method**: ``GET /_config`` +* **Request**: None +* **Response**: Returns a structure configuration name and value pairs, + organized by section +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +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: + +.. code-block:: http + + GET http://couchdb:5984/_config + Accept: application/json + +The response is the JSON structure: + +.. code-block:: javascript + + { + "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`` +======================== + +* **Method**: ``GET /_config/section`` +* **Request**: None +* **Response**: All the configuration values within a specified section +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +Gets the configuration structure for a single section. For example, to +retrieve the CouchDB configuration section values: + +.. code-block:: http + + GET http://couchdb:5984/_config/couchdb + Accept: application/json + +The returned JSON contains just the configuration values for this +section: + +.. code-block:: javascript + + { + "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`` +============================ + +* **Method**: ``GET /_config/section/key`` +* **Request**: None +* **Response**: Value of the specified key/section +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Request completed successfully. + +Gets a single configuration value from within a specific configuration +section. For example, to obtain the current log level: + +.. code-block:: http + + GET http://couchdb:5984/_config/log/level + Accept: application/json + +Returns the string of the log level: + +.. code-block:: javascript + + "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. + +.. _api-put-config: + +``PUT /_config/section/key`` +============================ + +* **Method**: ``PUT /_config/section/key`` +* **Request**: Value structure +* **Response**: Previous value +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **200**: + Configuration option updated successfully + + * **500**: + Error setting configuration + +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: + +.. code-block:: http + + 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`` +=============================== + +* **Method**: ``DELETE /_config/section/key`` +* **Request**: None +* **Response**: Previous value +* **Admin Privileges Required**: yes +* **Return Codes**: + + * **409**: + Supplied revision is incorrect or missing + +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: + +.. code-block:: http + + DELETE http://couchdb:5984/_config/uuids/algorithm + Content-Type: application/json + +The returned value is the last configured UUID function: + +.. code-block:: javascript + + "random"