You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/07/24 14:25:00 UTC
[23/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to fa11c25
Move api basics to the related group of articles.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/2c747953
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/2c747953
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/2c747953
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 2c747953fd3214bb71d3d528d95c149e42116ab8
Parents: fab08a2
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Jul 23 13:51:59 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Jul 24 10:48:37 2013 +0400
----------------------------------------------------------------------
share/doc/build/Makefile.am | 6 +-
share/doc/src/api-basics.rst | 463 -----------------------------------
share/doc/src/api/basics.rst | 462 ++++++++++++++++++++++++++++++++++
share/doc/src/api/index.rst | 43 ++++
share/doc/src/api/reference.rst | 42 ----
share/doc/src/index.rst | 3 +-
share/doc/src/intro.rst | 2 +-
7 files changed, 510 insertions(+), 511 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/share/doc/build/Makefile.am
----------------------------------------------------------------------
diff --git a/share/doc/build/Makefile.am b/share/doc/build/Makefile.am
index 743cd4f..c822195 100644
--- a/share/doc/build/Makefile.am
+++ b/share/doc/build/Makefile.am
@@ -46,6 +46,7 @@ html_files = \
html/_images/futon-overview.png \
html/_images/futon-replform.png \
html/_sources/api/authn.txt \
+ html/_sources/api/basics.txt \
html/_sources/api/configuration.txt \
html/_sources/api/database.txt \
html/_sources/api/design.txt \
@@ -67,7 +68,6 @@ html_files = \
html/_sources/config/services.txt \
html/_sources/config/intro.txt \
html/_sources/config/proxying.txt \
- html/_sources/api-basics.txt \
html/_sources/changelog.txt \
html/_sources/changes.txt \
html/_sources/contributing.txt \
@@ -102,6 +102,7 @@ html_files = \
html/_static/up.png \
html/_static/websupport.js \
html/api/authn.html \
+ html/api/basics.html \
html/api/configuration.html \
html/api/database.html \
html/api/design.html \
@@ -123,7 +124,6 @@ html_files = \
html/config/services.html \
html/config/intro.html \
html/config/proxying.html \
- html/api-basics.html \
html/changelog.html \
html/changes.html \
html/ddocs.html \
@@ -156,6 +156,7 @@ image_files = \
src_files = \
../src/api/authn.rst \
+ ../src/api/basics.rst \
../src/api/configuration.rst \
../src/api/database.rst \
../src/api/design.rst \
@@ -177,7 +178,6 @@ src_files = \
../src/config/services.rst \
../src/config/intro.rst \
../src/config/proxying.rst \
- ../src/api-basics.rst \
../src/changelog.rst \
../src/changes.rst \
../src/contributing.rst \
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/share/doc/src/api-basics.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api-basics.rst b/share/doc/src/api-basics.rst
deleted file mode 100644
index 8ffd83b..0000000
--- a/share/doc/src/api-basics.rst
+++ /dev/null
@@ -1,463 +0,0 @@
-.. 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:
-
-==========
-API Basics
-==========
-
-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.
-
-HTTP Range Requests
-===================
-
-HTTP allows you to specify byte ranges for requests. This allows the
-implementation of resumable downloads and skippable audio and video
-streams alike. This is available for all attachments inside CouchDB.
-
-This is just a real quick run through how this looks under the hood.
-Usually, you will have larger binary files to serve from CouchDB, like
-MP3s and videos, but to make things a little more obvious, I use a text
-file here (Note that I use the ``application/octet-stream`` Content-Type
-instead of ``text/plain``).
-
-.. code-block:: bash
-
- shell> cat file.txt
- My hovercraft is full of eels!
-
-Now let's store this text file as an attachment in CouchDB. First, we
-create a database:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/test
- {"ok":true}
-
-Then we create a new document and the file attachment in one go:
-
-.. code-block:: bash
-
- shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
- -H "Content-Type: application/octet-stream" -d@file.txt
- {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
-
-Now we can request the whole file easily:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
- My hovercraft is full of eels!
-
-But say we only want the first 13 bytes:
-
-.. code-block:: bash
-
- shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \
- -H "Range: bytes=0-12"
- My hovercraft
-
-HTTP supports many ways to specify single and even multiple byte
-ranges. Read all about it in `RFC 2616`_.
-
-.. note::
- Databases that have been created with CouchDB 1.0.2 or earlier will
- support range requests in |version|, 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 |version| to take advantage of a
- better algorithm to find byte ranges.
-
-.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/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..83b1445
--- /dev/null
+++ b/share/doc/src/api/basics.rst
@@ -0,0 +1,462 @@
+.. 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:
+
+==========
+API Basics
+==========
+
+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.
+
+.. _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.
+
+HTTP Range Requests
+===================
+
+HTTP allows you to specify byte ranges for requests. This allows the
+implementation of resumable downloads and skippable audio and video
+streams alike. This is available for all attachments inside CouchDB.
+
+This is just a real quick run through how this looks under the hood.
+Usually, you will have larger binary files to serve from CouchDB, like
+MP3s and videos, but to make things a little more obvious, I use a text
+file here (Note that I use the ``application/octet-stream`` Content-Type
+instead of ``text/plain``).
+
+.. code-block:: bash
+
+ shell> cat file.txt
+ My hovercraft is full of eels!
+
+Now let's store this text file as an attachment in CouchDB. First, we
+create a database:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/test
+ {"ok":true}
+
+Then we create a new document and the file attachment in one go:
+
+.. code-block:: bash
+
+ shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
+ -H "Content-Type: application/octet-stream" -d@file.txt
+ {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
+
+Now we can request the whole file easily:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
+ My hovercraft is full of eels!
+
+But say we only want the first 13 bytes:
+
+.. code-block:: bash
+
+ shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \
+ -H "Range: bytes=0-12"
+ My hovercraft
+
+HTTP supports many ways to specify single and even multiple byte
+ranges. Read all about it in `RFC 2616`_.
+
+.. note::
+ Databases that have been created with CouchDB 1.0.2 or earlier will
+ support range requests in |version|, 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 |version| to take advantage of a
+ better algorithm to find byte ranges.
+
+.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/share/doc/src/api/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/index.rst b/share/doc/src/api/index.rst
new file mode 100644
index 0000000..398a058
--- /dev/null
+++ b/share/doc/src/api/index.rst
@@ -0,0 +1,43 @@
+.. 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:
+
+API Reference
+=============
+
+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.
+
+This reference is structured according to the URL structure, as below.
+
+.. toctree::
+ :maxdepth: 2
+
+ basics
+ database
+ documents
+ design
+ local
+ configuration
+ authn
+ misc
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/share/doc/src/api/reference.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/reference.rst b/share/doc/src/api/reference.rst
deleted file mode 100644
index 59b3536..0000000
--- a/share/doc/src/api/reference.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-.. 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-overview:
-
-API Reference
-=============
-
-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.
-
-This reference is structured according to the URL structure, as below.
-
-.. toctree::
- :maxdepth: 2
-
- database
- documents
- local
- design
- misc
- configuration
- authn
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/share/doc/src/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/index.rst b/share/doc/src/index.rst
index b51c853..eef82ca 100644
--- a/share/doc/src/index.rst
+++ b/share/doc/src/index.rst
@@ -28,14 +28,13 @@ Contents
:numbered:
intro
- api-basics
config/index
replication
replicator
ddocs
query-servers
changes
- api/reference
+ api/index
json-structure
contributing
changelog
http://git-wip-us.apache.org/repos/asf/couchdb/blob/2c747953/share/doc/src/intro.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/intro.rst b/share/doc/src/intro.rst
index 8a831ee..faf6bcc 100644
--- a/share/doc/src/intro.rst
+++ b/share/doc/src/intro.rst
@@ -303,7 +303,7 @@ document ID that was returned:
"_rev":"1-33b9fbce46930280dab37d672bbc8bb9",
"company":"Example, Inc."}
-The API samples in the :ref:`api-basics` show the HTTP command, URL and any
+The API samples in the :ref:`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 ``curl`` with the
command-line examples shown above.