| .. 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/db: |
| |
| ======= |
| ``/db`` |
| ======= |
| |
| .. http:head:: /{db} |
| :synopsis: Checks the database existence |
| |
| Returns the HTTP Headers containing a minimal amount of information |
| about the specified database. Since the response body is empty, using the |
| HEAD method is a lightweight way to check if the database exists already or |
| not. |
| |
| :param db: Database name |
| :code 200: Database exists |
| :code 404: Requested database not found |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| HEAD /test HTTP/1.1 |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Cache-Control: must-revalidate |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 01:27:41 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| .. http:get:: /{db} |
| :synopsis: Returns the database information |
| |
| Gets information about the specified database. |
| |
| :param db: Database name |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json number cluster.n: Replicas. The number of copies of every document. |
| :>json number cluster.q: Shards. The number of range partitions. |
| :>json number cluster.r: Read quorum. The number of consistent copies |
| of a document that need to be read before a successful reply. |
| :>json number cluster.w: Write quorum. The number of copies of a document |
| that need to be written before a successful reply. |
| :>json boolean compact_running: Set to ``true`` if the database compaction |
| routine is operating on this database. |
| :>json string db_name: The name of the database. |
| :>json number disk_format_version: The version of the physical format used |
| for the data when it is stored on disk. |
| :>json number doc_count: A count of the documents in the specified |
| database. |
| :>json number doc_del_count: Number of deleted documents |
| :>json string instance_start_time: Always ``"0"``. (Returned for legacy |
| reasons.) |
| :>json string purge_seq: An opaque string that describes the purge state |
| of the database. Do not rely on this string for counting the number |
| of purge operations. |
| :>json number sizes.active: The size of live data inside the database, in |
| bytes. |
| :>json number sizes.external: The uncompressed size of database contents |
| in bytes. |
| :>json number sizes.file: The size of the database file on disk in bytes. |
| Views indexes are not included in the calculation. |
| :>json string update_seq: An opaque string that describes the state |
| of the database. Do not rely on this string for counting the number |
| of updates. |
| :>json boolean props.partitioned: (optional) If present and true, this |
| indicates that the database is partitioned. |
| :code 200: Request completed successfully |
| :code 404: Requested database not found |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| GET /receipts HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Cache-Control: must-revalidate |
| Content-Length: 258 |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 01:38:57 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "cluster": { |
| "n": 3, |
| "q": 8, |
| "r": 2, |
| "w": 2 |
| }, |
| "compact_running": false, |
| "db_name": "receipts", |
| "disk_format_version": 6, |
| "doc_count": 6146, |
| "doc_del_count": 64637, |
| "instance_start_time": "0", |
| "props": {}, |
| "purge_seq": 0, |
| "sizes": { |
| "active": 65031503, |
| "external": 66982448, |
| "file": 137433211 |
| }, |
| "update_seq": "292786-g1AAAAF..." |
| } |
| |
| .. http:put:: /{db} |
| :synopsis: Creates a new database |
| |
| Creates a new database. The database name ``{db}`` must be composed by |
| following next rules: |
| |
| - Name must begin with a lowercase letter (``a-z``) |
| |
| - Lowercase characters (``a-z``) |
| |
| - Digits (``0-9``) |
| |
| - Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and |
| ``/``. |
| |
| If you're familiar with `Regular Expressions`_, the rules above could be |
| written as ``^[a-z][a-z0-9_$()+/-]*$``. |
| |
| :param db: Database name |
| :query integer q: Shards, aka the number of range partitions. Default is |
| 8, unless overridden in the :config:option:`cluster config <cluster/q>`. |
| :query integer n: Replicas. The number of copies of the database in the |
| cluster. The default is 3, unless overridden in the |
| :config:option:`cluster config <cluster/n>` . |
| :query boolean partitioned: Whether to create a partitioned database. |
| Default is false. |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>header Location: Database URI location |
| :>json boolean ok: Operation status. Available in case of success |
| :>json string error: Error type. Available if response code is ``4xx`` |
| :>json string reason: Error description. Available if response code is |
| ``4xx`` |
| :code 201: Database created successfully (quorum is met) |
| :code 202: Accepted (at least by one node) |
| :code 400: Invalid database name |
| :code 401: CouchDB Server Administrator privileges required |
| :code 412: Database already exists |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| PUT /db HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 201 Created |
| Cache-Control: must-revalidate |
| Content-Length: 12 |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 08:01:45 GMT |
| Location: http://localhost:5984/db |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "ok": true |
| } |
| |
| If we repeat the same request to CouchDB, it will response with :code:`412` |
| since the database already exists: |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| PUT /db HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 412 Precondition Failed |
| Cache-Control: must-revalidate |
| Content-Length: 95 |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 08:01:16 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "error": "file_exists", |
| "reason": "The database could not be created, the file already exists." |
| } |
| |
| If an invalid database name is supplied, CouchDB returns response with |
| :code:`400`: |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| PUT /_db HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 400 Bad Request |
| Cache-Control: must-revalidate |
| Content-Length: 194 |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 08:02:10 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "error": "illegal_database_name", |
| "reason": "Name: '_db'. Only lowercase characters (a-z), digits (0-9), and any of the characters _, $, (, ), +, -, and / are allowed. Must begin with a letter." |
| } |
| |
| .. http:delete:: /{db} |
| :synopsis: Deletes an existing database |
| |
| Deletes the specified database, and all the documents and attachments |
| contained within it. |
| |
| .. note:: |
| To avoid deleting a database, CouchDB will respond with the HTTP status |
| code 400 when the request URL includes a ?rev= parameter. This suggests |
| that one wants to delete a document but forgot to add the document id |
| to the URL. |
| |
| :param db: Database name |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :>header Content-Type: - :mimetype:`application/json` |
| - :mimetype:`text/plain; charset=utf-8` |
| :>json boolean ok: Operation status |
| :code 200: Database removed successfully (quorum is met and database is deleted by at least one node) |
| :code 202: Accepted (deleted by at least one of the nodes, quorum is not met yet) |
| :code 400: Invalid database name or forgotten document id by accident |
| :code 401: CouchDB Server Administrator privileges required |
| :code 404: Database doesn't exist or invalid database name |
| |
| **Request**: |
| |
| .. code-block:: http |
| |
| DELETE /db HTTP/1.1 |
| Accept: application/json |
| Host: localhost:5984 |
| |
| **Response**: |
| |
| .. code-block:: http |
| |
| HTTP/1.1 200 OK |
| Cache-Control: must-revalidate |
| Content-Length: 12 |
| Content-Type: application/json |
| Date: Mon, 12 Aug 2013 08:54:00 GMT |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "ok": true |
| } |
| |
| .. http:post:: /{db} |
| :synopsis: Creates a new document with generated ID if _id is not specified |
| |
| 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, |
| following whatever UUID algorithm is configured for that server. |
| |
| :param db: Database name |
| :<header Accept: - :mimetype:`application/json` |
| - :mimetype:`text/plain` |
| :<header Content-Type: :mimetype:`application/json` |
| |
| :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 Location: Document's URI |
| |
| :>json string id: 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 exist |
| :code 409: A Conflicting Document with same 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 |
| Location: http://localhost:5984/db/ab39fe0993049b84cfa81acd6ebad09d |
| Server: CouchDB (Erlang/OTP) |
| |
| { |
| "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 (Erlang/OTP) |
| |
| { |
| "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 per-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. |
| |
| Batch mode is not suitable for critical data, but may be ideal for applications |
| such as log data, when the risk of some data loss due to a crash is acceptable. |
| |
| To use batch mode, append the ``batch=ok`` query argument to the URL of a |
| :post:`/{db}`, :put:`/{db}/{docid}`, or :delete:`/{db}/{docid}` request. The |
| CouchDB server will respond with an HTTP :statuscode:`202` response code |
| immediately. |
| |
| .. note:: |
| Creating or updating documents with batch mode doesn't guarantee that all |
| documents will be successfully stored on disk. For example, individual |
| documents may not be saved due to conflicts, rejection by |
| :ref:`validation function <vdufun>` or by other reasons, even if overall |
| the batch was successfully submitted. |
| |
| **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 (Erlang/OTP) |
| |
| { |
| "id": "FishStew", |
| "ok": true |
| } |
| |
| .. _Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression |