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:37:51 UTC
[24/50] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 360107b
Update base Database API ref.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/49164fa4
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/49164fa4
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/49164fa4
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 49164fa41a02df200de3532d39b4ecb982e133fb
Parents: e168cc1
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Aug 12 13:04:21 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Aug 21 20:29:39 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database/common.rst | 346 ++++++++++++++++------------
share/doc/src/api/database/compact.rst | 4 +-
share/doc/src/api/database/index.rst | 2 +-
share/doc/src/api/ddoc/views.rst | 2 +-
4 files changed, 207 insertions(+), 147 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49164fa4/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 14c72ec..4e07a4e 100644
--- a/share/doc/src/api/database/common.rst
+++ b/share/doc/src/api/database/common.rst
@@ -10,186 +10,246 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. _api/db.head:
+.. _api/db:
-``HEAD /db``
-============
+``/db``
+=======
-* **Method**: ``HEAD /db``
-* **Request**: None
-* **Response**: None
-* **Admin Privileges Required**: no
-* **Return Codes**:
+.. http:head:: /{db}
- * **200**:
- Database exists.
+ Returns the HTTP Headers containing a minimal amount of information
+ about the specified database. Since the response body is empty this method
+ is a lightweight way to check is database exists or not.
- * **404**:
- Requested database not found.
+ :param db: Database name
+ :code 200: Database exists
+ :code 404: Requested database not found
-Returns the HTTP Headers containing a minimal amount of information
-about the specified database. Since the response body is empty this method
-is a lightweight way to check is database exists or not.
+ **Request**:
-.. _api/db.get:
+ .. code-block:: http
-``GET /db``
-===========
+ HEAD /test HTTP/1.1
+ Host: localhost:5984
-* **Method**: ``GET /db``
-* **Request**: None
-* **Response**: Information about the database in JSON format
-* **Admin Privileges Required**: no
-* **Return Codes**:
+ **Response**:
- * **404**:
- The requested content could not be found. The returned content will include
- further information, as a JSON object, if available.
+ .. code-block:: http
-Gets information about the specified database. For example, to retrieve
-the information for the database ``recipe``:
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 01:27:41 GMT
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+
+
+.. http:get:: /{db}
+
+ 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 committed_update_seq: The number of committed update.
+ :>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 disk_size: Size in bytes of the data as stored on the disk.
+ Views indexes are not included in the calculation.
+ :>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: Timestamp of when the database was opened,
+ expressed in microseconds since the epoch.
+ :>json number purge_seq: The number of purge operations on the database.
+ :>json number update_seq: The current number of updates to the database.
+ :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/1.4.0 (Erlang OTP/R16B)
+
+ {
+ "committed_update_seq": 292786,
+ "compact_running": false,
+ "data_size": 65031503,
+ "db_name": "receipts",
+ "disk_format_version": 6,
+ "disk_size": 137433211,
+ "doc_count": 6146,
+ "doc_del_count": 64637,
+ "instance_start_time": "1376269325408900",
+ "purge_seq": 0,
+ "update_seq": 292786
+ }
+
+
+.. http::put /{db}
-.. code-block:: http
+ Creates a new database. The database name ``{db}`` must be composed by
+ following next rules:
- GET http://couchdb:5984/recipes
+ - 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
+ :<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
+ :code 400: Invalid database name
+ :code 401: Administrator`s privileges required
+ :code 412: Database already exists
+
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /db HTTP/1.1
Accept: application/json
+ Host: localhost:5984
-The JSON response contains meta information about the database. A sample
-of the JSON returned for an empty database is provided below:
+ **Response**:
-.. code-block:: javascript
+ .. 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/1.4.0 (Erlang OTP/R16B)
{
- "compact_running" : false,
- "committed_update_seq" : 375048,
- "disk_format_version" : 5,
- "disk_size" : 33153123,
- "doc_count" : 18386,
- "doc_del_count" : 0,
- "db_name" : "recipes",
- "instance_start_time" : "1290700340925570",
- "purge_seq" : 10,
- "update_seq" : 375048
+ "ok": true
}
+ If we repeat same request to CouchDB, it will response with :code:`412` since
+ database is already exists:
-The elements of the returned structure are shown in the table below:
-
-+----------------------------------+-------------------------------------------+
-| Field | Description |
-+==================================+===========================================+
-| committed_update_seq | The number of committed update. |
-+----------------------------------+-------------------------------------------+
-| compact_running | Set to true if the database compaction |
-| | routine is operating on this database. |
-+----------------------------------+-------------------------------------------+
-| db_name | The name of the database. |
-+----------------------------------+-------------------------------------------+
-| disk_format_version | The version of the physical format used |
-| | for the data when it is stored on disk. |
-+----------------------------------+-------------------------------------------+
-| disk_size | Size in bytes of the data as stored on the|
-| | disk. Views indexes are not included in |
-| | the calculation. |
-+----------------------------------+-------------------------------------------+
-| doc_count | A count of the documents in the specified |
-| | database. |
-+----------------------------------+-------------------------------------------+
-| doc_del_count | Number of deleted documents |
-+----------------------------------+-------------------------------------------+
-| instance_start_time | Timestamp of when the database was |
-| | opened, expressed in microseconds since |
-| | the epoch. |
-+----------------------------------+-------------------------------------------+
-| purge_seq | The number of purge operations on the |
-| | database. |
-+----------------------------------+-------------------------------------------+
-| update_seq | The current number of updates to the |
-| | database. |
-+----------------------------------+-------------------------------------------+
-
-.. _api/db.put:
-
-``PUT /db``
-===========
-
-* **Method**: ``PUT /db``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: no
-* **Return Codes**:
-
- * **400**:
- Invalid database name
-
- * **412**:
- Database already exists
-
-Creates a new database. The database name must be composed of one or
-more of the following characters:
-
-- Lowercase characters (``a-z``)
-
-- Name must begin with a lowercase letter
-
-- Digits (``0-9``)
-
-- Any of the characters ``_``, ``$``, ``(``, ``)``, ``+``, ``-``, and
- ``/``.
-
-Trying to create a database that does not meet these requirements will
-return an error quoting these restrictions.
-
-To create the database ``recipes``:
-
-.. code-block:: http
-
- PUT http://couchdb:5984/recipes
- Content-Type: application/json
+ **Request**:
+
+ .. code-block:: http
+
+ PUT /db HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
-The returned content contains the JSON status:
+ .. code-block:: http
-.. code-block:: javascript
+ 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/1.4.0 (Erlang OTP/R16B)
{
- "ok" : true
+ "error": "file_exists",
+ "reason": "The database could not be created, the file already exists."
}
-Anything should be treated as an error, and the problem should be taken
-form the HTTP response code.
+ In case of invalid database name CouchDB returns response with :code:`400`:
-.. _api/db.delete:
+ **Request**:
-``DELETE /db``
-==============
+ .. code-block:: http
-* **Method**: ``DELETE /db``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: no
-* **Return Codes**:
+ PUT /_db HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
- * **200**:
- Database has been deleted
+ **Request**:
- * **404**:
- The requested content could not be found. The returned content will include
- further information, as a JSON object, if available.
+ .. code-block:: http
-Deletes the specified database, and all the documents and attachments
-contained within it.
+ 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/1.4.0 (Erlang OTP/R16B)
-To delete the database ``recipes`` you would send the request:
+ {
+ "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."
+ }
-.. code-block:: http
- DELETE http://couchdb:5984/recipes
- Content-Type: application/json
+.. http:delete:: /{db}
-If successful, the returned JSON will indicate success
+ Deletes the specified database, and all the documents and attachments
+ contained within it.
-.. code-block:: javascript
+ :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
+ :code 400: Invalid database name
+ :code 401: Administrator`s privileges required
+ :code 404: Database doesn't already exists
+
+ **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/1.4.0 (Erlang OTP/R16B)
{
- "ok" : true
+ "ok": true
}
+
+
+.. _Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49164fa4/share/doc/src/api/database/compact.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/compact.rst b/share/doc/src/api/database/compact.rst
index 27a88c4..40a1f62 100644
--- a/share/doc/src/api/database/compact.rst
+++ b/share/doc/src/api/database/compact.rst
@@ -41,7 +41,7 @@ disk database file by performing the following operations:
- Removes old revisions of documents from the database, up to the
per-database limit specified by the ``_revs_limit`` database
- parameter. See :ref:`api/db.get`.
+ parameter.
Compaction can only be requested on an individual database; you cannot
compact all the databases for a CouchDB instance. The compaction process
@@ -50,7 +50,7 @@ runs as a background process.
You can determine if the compaction process is operating on a database
by obtaining the database meta information, the ``compact_running``
value of the returned database structure will be set to true. See
-:ref:`api/db.get`.
+:http:get:`/{db}`.
You can also obtain a list of running processes to determine whether
compaction is currently running. See :ref:`api/server/active_tasks`.
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49164fa4/share/doc/src/api/database/index.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/index.rst b/share/doc/src/api/database/index.rst
index 58be30b..92361e3 100644
--- a/share/doc/src/api/database/index.rst
+++ b/share/doc/src/api/database/index.rst
@@ -10,7 +10,7 @@
.. License for the specific language governing permissions and limitations under
.. the License.
-.. _api/db:
+.. _api/database:
================
Database Methods
http://git-wip-us.apache.org/repos/asf/couchdb/blob/49164fa4/share/doc/src/api/ddoc/views.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/ddoc/views.rst b/share/doc/src/api/ddoc/views.rst
index abc9e05..59b830b 100644
--- a/share/doc/src/api/ddoc/views.rst
+++ b/share/doc/src/api/ddoc/views.rst
@@ -228,7 +228,7 @@ In addition to using stale views, you can also make use of the
view information including the update sequence of the database from
which the view was generated. The returned value can be compared this to
the current update sequence exposed in the database information
-(returned by :ref:`api/db.get`).
+(returned by :http:get:`/{db}`).
Sorting Returned Rows
---------------------