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/08/21 18:38:04 UTC
[37/50] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 360107b
Move POST /db method to Database API reference.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/6d2dd984
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/6d2dd984
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/6d2dd984
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 6d2dd9845dcd392e84da59920a15c2b3f95394b9
Parents: 00e6c06
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Aug 13 22:44:53 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Aug 21 20:29:40 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/common.rst | 166 +++++++++++++++++++++++++
share/doc/src/api/document/common.rst | 190 -----------------------------
2 files changed, 166 insertions(+), 190 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6d2dd984/share/doc/src/api/database/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/common.rst b/share/doc/src/api/database/common.rst
index 4e07a4e..efc3b37 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -252,4 +252,170 @@
}
+.. http:post:: /{db}
+
+ Creates a new document in the specified database, using the supplied JSON
+ document structure.
+
+ If the JSON structure includes the ``_id`` field, then the document will be
+ created with the specified document ID.
+
+ If the ``_id`` field is not specified, a new unique ID will be generated.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/plain`
+ :<header Content-Type: :mimetype:`application/json`
+ :<header X-Couch-Full-Commit: Overrides server's
+ :ref:`commit policy <config/couchdb/delayed_commits>`. Possible values
+ are: ``false`` and ``true``. *Optional*.
+ :query string batch: Stores document in :ref:`batch mode
+ <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Quoted new document's revision
+ :>header Location: Document URI
+ :>json string id: Created document ID
+ :>json boolean ok: Operation status
+ :>json string rev: Revision info
+ :code 201: Document created and stored on disk
+ :code 202: Document data accepted, but not yet stored on disk
+ :code 400: Invalid database name
+ :code 401: Write privileges required
+ :code 404: Database doesn't already exists
+ :code 409: Document with the specified document ID already exists
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db HTTP/1.1
+ Accept: application/json
+ Content-Length: 81
+ Content-Type: application/json
+
+ {
+ "servings": 4,
+ "subtitle": "Delicious with fresh bread",
+ "title": "Fish Stew"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 95
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 15:19:25 GMT
+ ETag: "1-9c65296036141e575d32ba9c034dd3ee"
+ Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "ab39fe0993049b84cfa81acd6ebad09d",
+ "ok": true,
+ "rev": "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+
+
+Specifying the Document ID
+--------------------------
+
+The document ID can be specified by including the ``_id`` field in the
+JSON of the submitted record. The following request will create the same
+document with the ID ``FishStew``.
+
+ **Request**:
+
+ .. code-block:: http
+
+ POST /db HTTP/1.1
+ Accept: application/json
+ Content-Length: 98
+ Content-Type: application/json
+
+ {
+ "_id": "FishStew",
+ "servings": 4,
+ "subtitle": "Delicious with fresh bread",
+ "title": "Fish Stew"
+ }
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 201 Created
+ Cache-Control: must-revalidate
+ Content-Length: 71
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 15:19:25 GMT
+ ETag: "1-9c65296036141e575d32ba9c034dd3ee"
+ Location: http://localhost:5984/db/FishStew
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "FishStew",
+ "ok": true,
+ "rev": "1-9c65296036141e575d32ba9c034dd3ee"
+ }
+
+
+.. _api/doc/batch-writes:
+
+Batch Mode Writes
+-----------------
+
+You can write documents to the database at a higher rate by using the
+batch option. This collects document writes together in memory (on a
+user-by-user basis) before they are committed to disk. This increases
+the risk of the documents not being stored in the event of a failure,
+since the documents are not written to disk immediately.
+
+To use the batched mode, append the ``batch=ok`` query argument to the
+URL of the ``PUT`` or :http:post:`/{db}` request. The CouchDB server will
+respond with a HTTP :http:statuscode:`202` response code immediately.
+
+.. note::
+
+ Creating or updating documents with batch mode doesn't guarantees that
+ document will be successfully stored on disk and CouchDB doesn't ensures you
+ that it will to. Document may not be saved due to conflicts, rejection by
+ :ref:`validation function <vdufun>` or by other reasons.
+
+**Request**:
+
+.. code-block:: http
+
+ POST /db?batch=ok HTTP/1.1
+ Accept: application/json
+ Content-Length: 98
+ Content-Type: application/json
+
+ {
+ "_id": "FishStew",
+ "servings": 4,
+ "subtitle": "Delicious with fresh bread",
+ "title": "Fish Stew"
+ }
+
+**Response**:
+
+.. code-block:: http
+
+ HTTP/1.1 202 Accepted
+ Cache-Control: must-revalidate
+ Content-Length: 28
+ Content-Type: application/json
+ Date: Tue, 13 Aug 2013 15:19:25 GMT
+ Location: http://localhost:5984/db/FishStew
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "id": "FishStew",
+ "ok": true
+ }
+
.. _Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression
http://git-wip-us.apache.org/repos/asf/couchdb/blob/6d2dd984/share/doc/src/api/document/common.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/document/common.rst b/share/doc/src/api/document/common.rst
index 6ac9b2d..ff2aa65 100644
--- a/share/doc/src/api/document/common.rst
+++ b/share/doc/src/api/document/common.rst
@@ -11,196 +11,6 @@
.. the License.
-.. _api/db.post:
-
-``POST /db``
-============
-
-* **Method**: ``POST /db``
-* **Request**: JSON of the new document
-* **Response**: JSON with the committed document information
-* **Admin Privileges Required**: no
-* **Query Arguments**:
-
- * **Argument**: batch
-
- * **Description**: Allow document store request to be batched with others
- * **Optional**: yes
- * **Type**: string
- * **Supported Values**: asd
- * **ok**: Enable
-
-* **Return Codes**:
-
- * **201**:
- Document has been created successfully
- * **409**:
- Conflict - a document with the specified document ID already exists
-
-Create a new document in the specified database, using the supplied JSON
-document structure. If the JSON structure includes the ``_id`` field,
-then the document will be created with the specified document ID. If the
-``_id`` field is not specified, a new unique ID will be generated.
-
-For example, you can generate a new document with a generated UUID using
-the following request:
-
-.. code-block:: http
-
- POST http://couchdb:5984/recipes/
- Content-Type: application/json
-
- {
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The return JSON will specify the automatically generated ID and revision
-information:
-
-.. code-block:: javascript
-
- {
- "id" : "64575eef70ab90a2b8d55fc09e00440d",
- "ok" : true,
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
-
-Specifying the Document ID
---------------------------
-
-The document ID can be specified by including the ``_id`` field in the
-JSON of the submitted record. The following request will create the same
-document with the ID ``FishStew``:
-
-.. code-block:: http
-
- POST http://couchdb:5984/recipes/
- Content-Type: application/json
-
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- }
-
-The structure of the submitted document is as shown in the table below:
-
-In either case, the returned JSON will specify the document ID, revision
-ID, and status message:
-
-.. code-block:: javascript
-
- {
- "id" : "FishStew",
- "ok" : true,
- "rev" : "1-9c65296036141e575d32ba9c034dd3ee"
- }
-
-
-UUID generation algorithms
---------------------------
-
-CouchDB supports a number of different UUID generation algorithms for use
-in situations where a user-specified UUID does not make sense. These
-can be set simply by `PUT http://couchdb:5984/_config/uuids/algorithm`.
-
-
-+---------------+---------------------+------------------------------------+
-| Algorithm | Description | Sample UUID |
-+===============+=====================+====================================+
-| random | 128 bits of pure | - 43febce5675468a5467fb5467ce9e6c0 |
-| | random awesomeness | |
-+---------------+---------------------+------------------------------------+
-| sequential | monotonically | - f755c413badf66b22941313f9f001e28 |
-| | increasing ids with | - f755c413badf66b22941313f9f0024ca |
-| | random increments | - f755c413badf66b22941313f9f00332c |
-+---------------+---------------------+------------------------------------+
-| utc_random | time since start of | - 04cfa405381205204f75100d0241ccc3 |
-| | epoch, as 14 hex | - 04cfa4059c48e76e7c054bbe033dd8db |
-| | digits, followed by | - 04cfa405fce10b0df4c08f95e667cd2f |
-| | 18 random digits. | |
-+---------------+---------------------+------------------------------------+
-| utc_id | time since start of | - 04cfa718b00848_i_am_in_yer_couch |
-| & additional | epoch, as 14 hex | - 04cfa71d377aef_i_am_in_yer_couch |
-| parameter | digits, followed by | - 04cfa71e0deabd_i_am_in_yer_couch |
-| | utc_id_suffix. | |
-+---------------+---------------------+------------------------------------+
-
-.. note:: **Impact of UUID choices:**
- The choice of UUID has a significant impact on the layout of the B-tree,
- prior to compaction.
-
- For example, a sequential UUID algorithm during uploading thousands of
- documents, will avoid the need to rewrite many intermediate B-tree nodes.
- A random UUID algorithm may require rewriting intermediate nodes on a regular
- basis, with a corresponding decrease of throughput, and significant wasted
- space due to the append-only B-tree design.
-
- It is generally recommended to set your own UUIDs, or use the sequential
- algorithm unless you have a specific need and take into account the likely
- need for compaction to re-balance the B-tree and reclaim wasted space.
-
-.. _api/doc/batch-writes:
-
-Batch Mode Writes
------------------
-
-You can write documents to the database at a higher rate by using the
-batch option. This collects document writes together in memory (on a
-user-by-user basis) before they are committed to disk. This increases
-the risk of the documents not being stored in the event of a failure,
-since the documents are not written to disk immediately.
-
-To use the batched mode, append the ``batch=ok`` query argument to the
-URL of the ``PUT`` or ``POST`` request. The CouchDB server will respond
-with a 202 HTTP response code immediately.
-
-Including Attachments
----------------------
-
-You can include one or more attachments with a given document by
-incorporating the attachment information within the JSON of the
-document. This provides a simpler alternative to loading documents with
-attachments than making a separate call (see :ref:`api/doc/attachment.put`).
-
-* **_id** (optional): Document ID
-* **_rev** (optional): Revision ID (when updating an existing document)
-* **_attachments** (optional): Document Attachment
-
- * **filename**: Attachment information
-
- * **content_type**: MIME Content type string
- * **data**: File attachment content, Base64 encoded
-
-The ``filename`` will be the attachment name. For example, when sending
-the JSON structure below:
-
-.. code-block:: javascript
-
- {
- "_id" : "FishStew",
- "servings" : 4,
- "subtitle" : "Delicious with fresh bread",
- "title" : "Fish Stew"
- "_attachments" : {
- "styling.css" : {
- "content-type" : "text/css",
- "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=",
- },
- },
- }
-
-
-The attachment ``styling.css`` can be accessed using
-``/recipes/FishStew/styling.css``. For more information on attachments,
-see :ref:`api/doc/attachment.get`.
-
-The document data embedded in to the structure must be encoded using
-base64.
-
.. _api/doc.get:
``GET /db/doc``