CouchDB API

Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 38383 invoked by uid 99); 12 Dec 2012 20:33:59 -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:33:59 +0000 Received: by tyr.zones.apache.org (Postfix, from userid 65534) id A7B7B81B9C5; Wed, 12 Dec 2012 20:33:59 +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: [24/34] import Couchbase docs Message-Id: <20121212203359.A7B7B81B9C5@tyr.zones.apache.org> Date: Wed, 12 Dec 2012 20:33:59 +0000 (UTC) http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml b/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml new file mode 100644 index 0000000..714e5b0 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-api-introduction.xml @@ -0,0 +1,851 @@ + + + +%every.entities; +]> + + + 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 + . + + + + 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 . + + + + 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 + . + + + + 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 + . + + +

+ + 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: + + + +{ + "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. For more information, see + . + + +

+ +

+ + 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 + */*: + + + +GET /recipes HTTP/1.1 +Host: couchdb:5984 +Accept: */* + + + + The returned headers are: + + + +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: + + + +GET /recipes HTTP/1.1 +Host: couchdb:5984 +Accept: application/json + + + + The headers returned include the + application/json content type: + + + +Server: CouchDB/1.0.1 (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. + + + + + +

+ +

+ + 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: + + +"A String" + + + + + Boolean - a true or + false value. You can use these strings + directly. For example: + + +{ "value": true} + + + + + Array - a list of values enclosed in square brackets. For + example: + + +["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: + + + +{ + "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 + eval() 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. + + + + + 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). See + + . + + + +

+ +

+ + 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: + + +{"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. + + + + + +

+ +

+ + 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 + . + + + + + + /db/doc + + + + Document methods, those that create, store, update or delete + CouchDB documents and their attachments. For more information, + see . + + + + + + /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 + . + + + + + + /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 + . + + + + + + /_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 + . + + + + + + /_config + + + + Methods for getting, and settings, CouchDB configuration + parameters. For more information, see + . + + + + + + + +

+ + http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml new file mode 100644 index 0000000..7f8d86e --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-api-json-metasrc.xml @@ -0,0 +1,43 @@ + + +%every.entities; +]> + + + JSON Structure Reference + + + The following appendix provides a quick reference to all the JSON + structures that you can supply to CouchDB, or get in return to + requests. + + + + JSON Structures + + + + + + + + + + + + + + + + + + + + + + + + + http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml new file mode 100644 index 0000000..6bbd0f0 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-api-localdb-metasrc.xml @@ -0,0 +1,186 @@ + + +%every.entities; +]> + + + CouchDB API Server Local (non-replicating) Document Methods + + + The Local (non-replicating) document interface allows you to create + local documents that are not replicated to other databases. These + documents can be used to hold configuration or other information + that is required specifically on the local CouchDB instance. + + + + Local documents have the following limitations: + + + + + + + Local documents are not replicated to other databases. + + + + + + The ID of the local document must be known for the document to + accessed. You cannot obtain a list of local documents from the + database. + + + + + + Local documents are not output by views, or the + _all_docs view. + + + + + + + Local documents can be used when you want to store configuration or + other information for the curent (local) instance of a given + database. + + + + A list of the available methods and URL paths are provided below: + + + + Local (non-replicating) Document API + Calls + + + + + + + + + + + + + + +

+ + <literal>GET /db/_local/local-doc</literal> + + + + + + + + + + + + + + + + + Gets the specified local document. The semantics are identical to + accessing a standard document in the specified database, except + that the document is not replicated. See + . + + +

+ +

+ + <literal>PUT /db/_local/local-doc</literal> + + + + + + + + + + + + + + + + + Stores the specified local document. The semantics are identical + to storing a standard document in the specified database, except + that the document is not replicated. See + . + + +

+ +

+ + <literal>DELETE /db/_local/local-doc</literal> + + + + + + + + + + + + + + + + + Deletes the specified local document. The semantics are identical + to deleting a standard document in the specified database, except + that the document is not replicated. See + . + + +

+ +

+ + <literal>COPY /db/_local/local-doc</literal> + + + + + + + + + + + + + + + + + Copies the specified local document. The semantics are identical + to copying a standard document in the specified database, except + that the document is not replicated. See + . + + +

+ + http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml new file mode 100644 index 0000000..200749f --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-api-misc-metasrc.xml @@ -0,0 +1,1357 @@ + + +%every.entities; +]> + + + CouchDB API Server Miscellaneous Methods + + + The CouchDB Miscellaneous interface provides the basic interface to + a CouchDB server for obtaining CouchDB information and getting and + setting configuration information. + + + + A list of the available methods and URL paths are provided below: + + + + Miscellaneous API Calls + + + + + + + + + + + + + + +

+ + <literal>GET /</literal> + + + + + + + + + + + + + + + + + Accessing the root of a CouchDB instance returns meta information + about the instance. The response is a JSON structure containing + information about the server, including a welcome message and the + version of the server. + + + +{ + "couchdb" : "Welcome", + "version" : "1.0.1" +} + + +

+ +

+ + <literal>GET /_active_tasks</literal> + + + + + + + + + + + + + + + + + You can obtain a list of active tasks by using the + /_active_tasks URL. The result is a JSON array + of the currently running tasks, with each task being described + with a single object. For example: + + + + +", + "status" : "Copied 0 of 18369 changes (0%)", + "task" : "recipes", + "type" : "Database Compaction" + } +] +]]> + + + + + The returned structure includes the following fields for each + task: + + + + + + + + + + + + + + + + For operation type, valid values include: + + + + + + + Database Compaction + + + + + + Replication + + + + + + View Group Compaction + + + + + + View Group Indexer + + + + + +

+ +

+ + <literal>GET /_all_dbs</literal> + + + + + + + + + + + + + + + + + Returns a list of all the databases in the CouchDB instance. For + example: + + + +GET http://couchdb:5984/_all_dbs +Accept: application/json + + + + The return is a JSON array: + + + +[ + "_users", + "contacts", + "docs", + "invoices", + "locations" +] + + + +

+ +

+ + <literal>GET /_log</literal> + + + + + + + + + + + + + + + + + Gets the CouchDB log, equivalent to accessing the local log file + of the corresponding CouchDB instance. + + + + When you request the log, the response is returned as plain + (UTF-8) text, with an HTTP Content-type header + as text/plain. + + + + For example, the request: + + + +GET http://couchdb:5984/_log +Accept: */* + + + + The raw text is returned: + + + +] 192.168.0.2 - - 'PUT' /authdb 401 + +[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /recipes/FishStew 200 + +[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.23428.2>] 192.168.0.116 - - 'GET' /_session 200 + +[Wed, 27 Oct 2010 11:02:19 GMT] [info] [<0.24199.2>] 192.168.0.116 - - 'GET' / 200 + +[Wed, 27 Oct 2010 13:03:38 GMT] [info] [<0.24207.2>] 192.168.0.116 - - 'GET' /_log?offset=5 200 +]]> + + + + If you want to pick out specific parts of the log information you + can use the bytes argument, which specifies the + number of bytes to be returned, and offset, + which specifies where the reading of the log should start, counted + back from the end. For example, if you use the following request: + + + +GET /_log?bytes=500&offset=2000 + + + + Reading of the log will start at 2000 bytes from the end of the + log, and 500 bytes will be shown. + + +

+ +

+ + <literal>POST /_replicate</literal> + + + + + + + + + + + + + + + + + Request, configure, or stop, a replication operation. + + + + The specification of the replication request is controlled through + the JSON content of the request. The JSON should be an object with + the fields defining the source, target and other options. The + fields of the JSON request are shown in the table below: + + + + + + + + + + + + + + +

+ + Replication Operation + + + The aim of the replication is that at the end of the process, + all active documents on the source database are also in the + destination database and all documents that were deleted in the + source databases are also deleted (if they exist) on the + destination database. + + + + Replication can be described as either push or pull replication: + + + + + + + Pull replication is where the + source is the remote CouchDB instance, + and the destination is the local + database. + + + + Pull replication is the most useful solution to use if your + source database has a permanent IP address, and your + destination (local) database may have a dynamically assigned + IP address (for example, through DHCP). This is particularly + important if you are replicating to a mobile or other device + from a central server. + + + + + + Push replication is where the + source is a local database, and + destination is a remote database. + + + + + +

+ +

+ + Specifying the Source and Target Database + + + You must use the URL specification of the CouchDB database if + you want to perform replication in either of the following two + situations: + + + + + + + Replication with a remote database (i.e. another instance of + CouchDB on the same host, or a different host) + + + + + + Replication with a database that requires authentication + + + + + + + For example, to request replication between a database local to + the CouchDB instance to which you send the request, and a remote + database you might use the following request: + + + +POST http://couchdb:5984/_replicate +Content-Type: application/json +Accept: application/json + +{ + "source" : "recipes", + "target" : "http://coucdb-remote:5984/recipes", +} + + + + In all cases, the requested databases in the + source and target + specification must exist. If they do not, an error will be + returned within the JSON object: + + + +{ + "error" : "db_not_found" + "reason" : "could not open http://couchdb-remote:5984/ol1ka/", +} + + + + You can create the target database (providing your user + credentials allow it) by adding the + create_target field to the request object: + + + +POST http://couchdb:5984/_replicate +Content-Type: application/json +Accept: application/json + +{ + "create_target" : true + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", +} + + + + The create_target field is not destructive. + If the database already exists, the replication proceeds as + normal. + + +

+ +

+ + Single Replication + + + You can request replication of a database so that the two + databases can be synchronized. By default, the replication + process occurs one time and synchronizes the two databases + together. For example, you can request a single synchronization + between two databases by supplying the source + and target fields within the request JSON + content. + + + +POST http://couchdb:5984/_replicate +Content-Type: application/json +Accept: application/json + +{ + "source" : "recipes", + "target" : "recipes-snapshot", +} + + + + In the above example, the databases recipes + and recipes-snapshot will be synchronized. + These databases are local to the CouchDB instance where the + request was made. The response will be a JSON structure + containing the success (or failure) of the synchronization + process, and statistics about the process: + + + +{ + "ok" : true, + "history" : [ + { + "docs_read" : 1000, + "session_id" : "52c2370f5027043d286daca4de247db0", + "recorded_seq" : 1000, + "end_last_seq" : 1000, + "doc_write_failures" : 0, + "start_time" : "Thu, 28 Oct 2010 10:24:13 GMT", + "start_last_seq" : 0, + "end_time" : "Thu, 28 Oct 2010 10:24:14 GMT", + "missing_checked" : 0, + "docs_written" : 1000, + "missing_found" : 1000 + } + ], + "session_id" : "52c2370f5027043d286daca4de247db0", + "source_last_seq" : 1000 +} + + + + The structure defines the replication status, as described in + the table below: + + + + + + + + + + + + + + +

+ +

+ + Continuous Replication + + + Synchronization of a database with the previously noted methods + happens only once, at the time the replicate request is made. To + have the target database permanently replicated from the source, + you must set the continuous field of the JSON + object within the request to true. + + + + With continuous replication changes in the source database are + replicated to the target database in perpetuity until you + specifically request that replication ceases. + + + +POST http://couchdb:5984/_replicate +Content-Type: application/json +Accept: application/json + +{ + "continuous" : true + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", +} + + + + Changes will be replicated between the two databases as long as + a network connection is available between the two instances. + + + + + Two keep two databases synchronized with each other, you need + to set replication in both directions; that is, you must + replicate from databasea to + databaseb, and separately from + databaseb to databasea. + + + +

+ +

+ + Canceling Continuous Replication + + + You can cancel continuous replication by adding the + cancel field to the JSON request object and + setting the value to true. Note that the structure of the + request must be identical to the original for the cancelation + request to be honoured. For example, if you requested continuous + replication, the cancellation request must also contain the + continuous field. + + + + For example, the replication request: + + + +POST http://couchdb:5984/_replicate +Content-Type: application/json +Accept: application/json + +{ + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", + "create_target" : true, + "continuous" : true +} + + + + Must be canceled using the request: + + + +POST http://couchdb:5984/_replicate +Content-Type: application/json +Accept: application/json + +{ + "cancel" : true, + "continuous" : true + "create_target" : true, + "source" : "recipes", + "target" : "http://couchdb-remote:5984/recipes", +} + + + + Requesting cancellation of a replication that does not exist + results in a 404 error. + + +

+ +

+ + <literal>POST /_restart</literal> + + + + + + + + + + + + + + + + + Restarts the CouchDB instance. You must be authenticated as a user + with administration privileges for this to work. + + + + For example: + + + +POST http://admin:password@couchdb:5984/_restart + + + + The return value (if the server has not already restarted) is a + JSON status object indicating that the request has been received: + + + +{ + "ok" : true, +} + + + + If the server has already restarted, the header may be returned, + but no actual data is contained in the response. + + +

+ +

+ + <literal>GET /_stats</literal> + + + + + + + + + + + + + + + + + The _stats method returns a JSON object + containting the statistics for the running server. The object is + structured with top-level sections collating the statistics for a + range of entries, with each individual statistic being easily + identified, and the content of each statistic is self-describing. + For example, the request time statistics, within the + couchdb section are structured as follows: + + + +{ + "couchdb" : { +... + "request_time" : { + "stddev" : "27.509", + "min" : "0.333333333333333", + "max" : "152", + "current" : "400.976", + "mean" : "10.837", + "sum" : "400.976", + "description" : "length of a request inside CouchDB without MochiWeb" + }, +... + } +} + + + + The fields provide the current, minimum and maximum, and a + collection of statistical means and quantities. The quantity in + each case is not defined, but the descriptions below provide + + + + The statistics are divided into the following top-level sections: + + + + + + + couchdb + + + + Describes statistics specific to the internals of CouchDB. + + + + <literal>couchdb</literal> statistics + + + + + + + + Statistic ID + + + Description + + + Unit + + + + + + auth_cache_hits + + + Number of authentication cache hits + + + number + + + + auth_cache_misses + + + Number of authentication cache misses + + + number + + + + database_reads + + + Number of times a document was read from a database + + + number + + + + database_writes + + + Number of times a database was changed + + + number + + + + open_databases + + + Number of open databases + + + number + + + + open_os_files + + + Number of file descriptors CouchDB has open + + + number + + + + request_time + + + Length of a request inside CouchDB without MochiWeb + + + milliseconds + + + + +

+ + + + + httpd_request_methods + + + + <literal>httpd_request_methods</literal> statistics + + + + + + + + Statistic ID + + + Description + + + Unit + + + + + + COPY + + + Number of HTTP COPY requests + + + number + + + + DELETE + + + Number of HTTP DELETE requests + + + number + + + + GET + + + Number of HTTP GET requests + + + number + + + + HEAD + + + Number of HTTP HEAD requests + + + number + + + + POST + + + Number of HTTP POST requests + + + number + + + + PUT + + + Number of HTTP PUT requests + + + number + + + + +

+ + + + + httpd_status_codes + + + + <literal>httpd_status_codes</literal> statistics + + + + + + + + Statistic ID + + + Description + + + Unit + + + + + + 200 + + + Number of HTTP 200 OK responses + + + number + + + + 201 + + + Number of HTTP 201 Created responses + + + number + + + + 202 + + + Number of HTTP 202 Accepted responses + + + number + + + + 301 + + + Number of HTTP 301 Moved Permanently responses + + + number + + + + 304 + + + Number of HTTP 304 Not Modified responses + + + number + + + + 400 + + + Number of HTTP 400 Bad Request responses + + + number + + + + 401 + + + Number of HTTP 401 Unauthorized responses + + + number + + + + 403 + + + Number of HTTP 403 Forbidden responses + + + number + + + + 404 + + + Number of HTTP 404 Not Found responses + + + number + + + + 405 + + + Number of HTTP 405 Method Not Allowed responses + + + number + + + + 409 + + + Number of HTTP 409 Conflict responses + + + number + + + + 412 + + + Number of HTTP 412 Precondition Failed responses + + + number + + + + 500 + + + Number of HTTP 500 Internal Server Error responses + + + number + + + + +

+ + + + + httpd + + + + <literal>httpd</literal> statistics + + + + + + + + Statistic ID + + + Description + + + Unit + + + + + + bulk_requests + + + Number of bulk requests + + + number + + + + clients_requesting_changes + + + Number of clients for continuous _changes + + + number + + + + requests + + + Number of HTTP requests + + + number + + + + temporary_view_reads + + + Number of temporary view reads + + + number + + + + view_reads + + + Number of view reads + + + number + + + + +

+ + + + + + You can also access individual statistics by quoting the + statistics sections and statistic ID as part of the URL path. For + example, to get the request_time statistics, + you can use: + + + +GET /_stats/couchdb/request_time + + + + This returns an entire statistics object, as with the full + request, but containining only the request individual statistic. + Hence, the returned structure is as follows: + + + +{ + "couchdb" : { + "request_time" : { + "stddev" : 7454.305, + "min" : 1, + "max" : 34185, + "current" : 34697.803, + "mean" : 1652.276, + "sum" : 34697.803, + "description" : "length of a request inside CouchDB without MochiWeb" + } + } +} + + +

+ +

+ + <literal>GET /_utils</literal> + + + + + + + + + + + + + + + + + Accesses the built-in Futon administration interface for CouchDB. + + +

+ +

+ + <literal>GET /_uuids</literal> + + + + + + + + + + + + + + + + + Requests one or more Universally Unique Identifiers (UUIDs) from + the CouchDB instance. The response is a JSON object providing a + list of UUIDs. For example: + + + +{ + "uuids" : [ + "7e4b5a14b22ec1cf8e58b9cdd0000da3" + ] +} + + + + You can use the count argument to specify the + number of UUIDs to be returned. For example: + + + + GET http://couchdb:5984/_uuids?count=5 + + + + Returns: + + + +{ + "uuids" : [ + "c9df0cdf4442f993fc5570225b405a80", + "c9df0cdf4442f993fc5570225b405bd2", + "c9df0cdf4442f993fc5570225b405e42", + "c9df0cdf4442f993fc5570225b4061a0", + "c9df0cdf4442f993fc5570225b406a20" + ] +} + + + + The UUID type is determined by the UUID type setting in the + CouchDB configuration. See + . + + + + For example, changing the UUID type to random: + + + +PUT http://couchdb:5984/_config/uuids/algorithm +Content-Type: application/json +Accept: */* + +"random" + + + + When obtaining a list of UUIDs: + + + +{ + "uuids" : [ + "031aad7b469956cf2826fcb2a9260492", + "6ec875e15e6b385120938df18ee8e496", + "cff9e881516483911aa2f0e98949092d", + "b89d37509d39dd712546f9510d4a9271", + "2e0dbf7f6c4ad716f21938a016e4e59f" + ] +} + + +

+ +

+ + <literal>GET /favicon.ico</literal> + + + + + + + + + + + + + + + + + Returns the site icon. The return Content-type + header is image/x-icon, and the content stream + is the image data. + + +

+ + http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml new file mode 100644 index 0000000..3387486 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-changes-metasrc.xml @@ -0,0 +1,67 @@ + + +%every.entities; +]> + + + Changes Feed + + + + + + + + + + + + + + + + + +

+ + Polling + + + + + +

+ +

+ + Long Polling + + + + + +

+ +

+ + Continuous + + + + + +

+ +

+ + Filters + + + + + +

+ + http://git-wip-us.apache.org/repos/asf/couchdb/blob/749f8c8c/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml ---------------------------------------------------------------------- diff --git a/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml b/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml new file mode 100644 index 0000000..d8a5fa5 --- /dev/null +++ b/share/docs/couchdb-manual-1.1/couchdb-config-options-metasrc.xml @@ -0,0 +1,393 @@ + + +%every.entities; +]> +

+ + CouchDB Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + +

+ + <literal>attachments</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>couchdb</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>daemons</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>httpd_db_handlers</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>couch_httpd_auth</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>httpd</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>httpd_design_handlers</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>httpd_global_handlers</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>log</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>query_servers</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>query_server_config</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>replicator</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>stats</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +

+ + <literal>uuids</literal> Configuration Options + + + + + + + Configuration Groups + + + + + + + + + + + + + + +

+ +