Return-Path: Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: (qmail 64649 invoked from network); 27 Oct 2009 23:28:38 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 27 Oct 2009 23:28:38 -0000 Received: (qmail 79411 invoked by uid 500); 27 Oct 2009 21:41:57 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 79344 invoked by uid 500); 27 Oct 2009 21:41:57 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 79335 invoked by uid 500); 27 Oct 2009 21:41:57 -0000 Delivered-To: apmail-incubator-couchdb-commits@incubator.apache.org Received: (qmail 79332 invoked by uid 99); 27 Oct 2009 21:41:57 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 27 Oct 2009 21:41:57 +0000 X-ASF-Spam-Status: No, hits=-2.6 required=5.0 tests=AWL,BAYES_00,WEIRD_PORT X-Spam-Check-By: apache.org Received: from [140.211.11.130] (HELO eos.apache.org) (140.211.11.130) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 27 Oct 2009 21:41:55 +0000 Received: from eos.apache.org (localhost [127.0.0.1]) by eos.apache.org (Postfix) with ESMTP id 99CB116E31; Tue, 27 Oct 2009 21:41:34 +0000 (GMT) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable From: Apache Wiki To: Apache Wiki Date: Tue, 27 Oct 2009 21:41:34 -0000 Message-ID: <20091027214134.19219.59364@eos.apache.org> Subject: =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22HTTP=5FDocument=5FAPI=22_by_Ran?= =?utf-8?q?dallLeeds?= Dear Wiki user, You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for c= hange notification. The "HTTP_Document_API" page has been changed by RandallLeeds. The comment on this change is: A few _revs where there should be no undersc= ore. http://wiki.apache.org/couchdb/HTTP_Document_API?action=3Ddiff&rev1=3D55&re= v2=3D56 -------------------------------------------------- This is an introduction to the CouchDB HTTP document API. = =3D=3D Naming/Addressing =3D=3D - = Documents stored in a CouchDB have a DocID. DocIDs are case-sensitive str= ing identifiers that uniquely identify a document. Two documents cannot hav= e the same identifier in the same database, they are considered the same do= cument. = {{{ @@ -11, +10 @@ http://localhost:5984/test/another_doc_id http://localhost:5984/test/BA1F48C5418E4E68E5183D5BD1F06476 }}} - = The above URLs point to ''some_doc_id'', ''another_doc_id'' and ''BA1F48C= 5418E4E68E5183D5BD1F06476'' in the database ''test''. = =3D=3D Documents =3D=3D - = A CouchDB document is simply a JSON object. You can use any JSON structur= e with nesting. You can fetch the document's revision information by adding= ''?revs=3Dtrue'' or ''?revs_info=3Dtrue'' to the get request. = Here are two simple examples of documents: + = {{{ { "_id":"discussion_tables", @@ -32, +30 @@ ] } }}} - = - = {{{ { "_id":"some_doc_id", @@ -45, +41 @@ "Body":"I decided today that I don't like baseball. I like plankton." } }}} - = =3D=3D=3D Special Fields =3D=3D=3D Note that any top-level fields with a name that starts with a ''_'' prefi= x are reserved for use by CouchDB itself. Also see [[Reserved_words]]. Curr= ently (0.10+) reserved fields are: = @@ -58, +53 @@ ''_conflicts'':: Information about conflicts ''_deleted_conflicts'':: Information about conflicts = - = =3D=3D=3D=3D Document IDs =3D=3D=3D=3D - = You can have '''/''' as part of the DocID but if you refer to a document = in a URL you must always encode it as '''%2F'''. One special case is '''_de= sign/''' documents, those accept either '''/''' or '''%2F''' for the '''/''= ' after ''_design'', although '''/''' is preferred and %2F is still needed = for the rest of the DocID. = '''Q: What's the rule on a valid document id? The examples suggest it's r= estricted to ''[a-zA-Z0-9_]''? What about multi-byte UTF-8 characters? Any = other non alphanums other than ''_''?''' @@ -69, +62 @@ = The reason database names have strict restrictions is to simplify databas= e name-to-file mapping. Since databases will need to replicate across opera= ting systems, the file naming scheme needed to be the lowest common denomin= ator. = - = =3D=3D Working With Documents Over HTTP =3D=3D - = =3D=3D=3D GET =3D=3D=3D - = To retrieve a document, simply perform a ''GET'' operation at the documen= t's URL: = {{{ GET /somedatabase/some_doc_id HTTP/1.0 }}} - = Here is the server's response: = {{{ @@ -98, +87 @@ "Body":"I decided today that I don't like baseball. I like plankton." } }}} - = =3D=3D=3D Accessing Previous Revisions =3D=3D=3D - = - See [[DocumentRevisions]] for additional notes on revisions. + See DocumentRevisions for additional notes on revisions. = The above example gets the current revision. You may be able to get a spe= cific revision by using the following syntax: = {{{ GET /somedatabase/some_doc_id?rev=3D946B7D1C HTTP/1.0 }}} - = To find out what revisions are available for a document, you can do: = {{{ GET /somedatabase/some_doc_id?revs=3Dtrue HTTP/1.0 }}} - = This returns the current revision of the document, but with an additional= field, ''_revisions'', the value being a list of the available revision ID= s. ''Note though that not every of those revisions of the document is neces= sarily still available.'' For example, the content of an old revision get r= emoved by compacting the database, or it may only exist in a different data= base if it was replicated. = To get more detailed information about the available document revisions, = use the ''revs_info'' parameter instead. In this case, the JSON result will= contain a ''_revs_info'' property, which is an array of objects, for examp= le: @@ -128, +113 @@ ] } }}} - = Here, ''disk'' means the revision content is stored on disk and can still= be retrieved. The other values indicate that the content of that revision = is not available. = <> + = =3D=3D=3D PUT =3D=3D=3D - = To create new document you can either use a ''POST'' operation or a ''PUT= '' operation. To create/update a named document using the PUT operation, th= e URL must point to the document's location. = The following is an example HTTP ''PUT''. It will cause the CouchDB serve= r to generate a new revision ID and save the document with it. @@ -151, +135 @@ "Body":"I decided today that I don't like baseball. I like plankton." } }}} - = Here is the server's response. = {{{ @@ -162, +145 @@ = {"ok": true, "id": "some_doc_id", "rev": "946B7D1C"} }}} - = To update an existing document, you also issue a ''PUT'' request. In this= case, the JSON body must contain a ''_rev'' property, which lets CouchDB k= now which revision the edits are based on. If the revision of the document = currently stored in the database doesn't match, then a ''409'' conflict err= or is returned. = If the revision number does match what's in the database, a new revision = number is generated and returned to the client. @@ -184, +166 @@ "Body":"I decided today that I don't like baseball. I like plankton." } }}} - = Here is the server's response if what is stored in the database is revisi= on ''946B7D1C'' of document ''some_doc_id''. = {{{ @@ -195, +176 @@ = {"ok":true, "id":"some_doc_id", "rev":"2774761002"} }}} - = And here is the server's response if there is an update conflict (what is= currently stored in the database is not revision ''946B7D1C'' of document = ''some_doc_id''). = {{{ @@ -206, +186 @@ = {"error":"conflict","reason":"Document update conflict."} }}} - = - There is a query option ''batch=3Dok'' which can be used to achieve highe= r throughput at the cost of lower guarantees. When a ''PUT'' (or a document= ''POST'' as described below) is sent using this option, it is not immediat= ely written to disk. Instead it is stored in memory on a per-user basis for= a second or so (or the number of docs in memory reaches a certain point). = After the threshold has passed, the docs are committed to disk. Instead of = waiting for the doc to be written to disk before responding, CouchDB sends = an HTTP ''202 Accepted'' response immediately. = + There is a query option ''batch=3Dok'' which can be used to achieve highe= r throughput at the cost of lower guarantees. When a ''PUT'' (or a document= ''POST'' as described below) is sent using this option, it is not immediat= ely written to disk. Instead it is stored in memory on a per-user basis for= a second or so (or the number of docs in memory reaches a certain point). = After the threshold has passed, the docs are committed to disk. Instead of = waiting for the doc to be written to disk before responding, CouchDB sends = an HTTP ''202 Accepted'' response immediately. = ''batch=3Dok'' is not suitable for crucial data, but it ideal for applica= tions like logging which can accept the risk that a small proportion of upd= ates could be lost due to a crash. Docs in the batch can also be flushed ma= nually using the ''_ensure_full_commit'' API. = =3D=3D=3D POST =3D=3D=3D - = The ''POST'' operation can be used to create a new document with a server= generated DocID. To create a named document, use the ''PUT'' method instea= d. It is recommended that you avoid ''POST'' when possible, because proxies= and other network intermediaries will occasionally resend ''POST'' request= s, which can result in duplicate document creation. If your client software= is not capable of guaranteeing uniqueness of generated UUIDs, use a ''GET'= ' to ''/_uuids?count=3D100'' to retrieve a list of document IDs for future = ''PUT'' requests. Please note that the ''/_uuids''-call does not check for = existing document ids; collision-detection happens when you are trying to s= ave a document. = The following is an example HTTP ''POST''. It will cause the CouchDB serv= er to generate a new DocID and revision ID and save the document with it. @@ -230, +208 @@ "Body":"I decided today that I don't like baseball. I like plankton." } }}} - = Here is the server's response: = {{{ @@ -240, +217 @@ Connection: close = {"ok":true, "id":"123BAC", "rev":"946B7D1C"} - = }}} - = - = =3D=3D=3D DELETE =3D=3D=3D - = To delete a document, perform a ''DELETE'' operation at the document's lo= cation, passing the ''rev'' parameter with the document's current revision.= If successful, it will return the revision id for the deletion stub. = {{{ DELETE /somedatabase/some_doc?rev=3D1582603387 HTTP/1.0 }}} - = As an alternative you can submit the ''rev'' parameter with the etag head= er field ''If-Match''. + = {{{ DELETE /somedatabase/some_doc HTTP/1.0 If-Match: "1582603387" }}} - = And the response: = {{{ @@ -268, +240 @@ = {"ok":true,"rev":"2839830636"} }}} - = - = =3D=3D=3D COPY =3D=3D=3D - = Note that this is a non-standard extension to HTTP. = You can copy documents by sending an HTTP COPY request. This allows you t= o duplicate the contents (and attachments) of a document to a new document = under a different document id without first retrieving it from CouchDB. Use= the ''Destination'' header to specify the document that you want to copy t= o (the target document). @@ -282, +251 @@ COPY /somedatabase/some_doc HTTP/1.1 Destination: some_other_doc }}} - = If you want to overwrite an existing document, you need to specify the ta= rget document's revision with a ''rev'' parameter in the ''Destination'' he= ader: = {{{ COPY /somedatabase/some_doc HTTP/1.1 Destination: some_other_doc?rev=3Drev_id }}} - = The response in both cases includes the target document's revision: = {{{ @@ -302, +269 @@ Cache-Control: must-revalidate = {"ok":true,"id":"some_other_doc","rev":"355068078"} - = }}} - = - = =3D=3D=3D MOVE =3D=3D=3D - = For a ~6 month period CouchDB trunk between versions 0.8 and 0.9 included= the nonstandard MOVE method. Since MOVE is really just COPY & DELETE and C= ouchDB can not reasonably guarantee atomicity between the COPY & MOVE opera= tions on a single or on multiple nodes, this was removed before the release= of CouchDB 0.9. - = = =3D=3D=3D Bulk Docs =3D=3D=3D - = For information about editing multiple documents at the same time, see [[= HTTP_Bulk_Document_API]] = - = =3D=3D All Documents =3D=3D - = To get a listing of all documents in a database, use the special ''_all_d= ocs'' URI. This is a specialized View so the Querying Options of the [[HTTP= _view_API]] apply here. = - = {{{ GET somedatabase/_all_docs HTTP/1.0 }}} - = Will return a listing of all documents and their revision IDs, ordered by= DocID (case sensitive): = {{{ @@ -341, +298 @@ ] } }}} - = Use the query argument ''descending=3Dtrue'' to reverse the order of the = output table: = Will return the same as before but in reverse order: @@ -354, +310 @@ = { "total_rows": 3, "offset": 0, "rows": [ - {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}} + {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}} - {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}}, + {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}}, - {"id": "doc1", "key": "doc1", "value": {"_rev": "4324BB"}}, + {"id": "doc1", "key": "doc1", "value": {"rev": "4324BB"}}, ] } }}} - = The query string parameters ''startkey'', ''endkey'' and ''limit'' may al= so be used to limit the result set. For example: = {{{ GET somedatabase/_all_docs?startkey=3D"doc2"&limit=3D2 HTTP/1.0 }}} - = Will return: = {{{ @@ -377, +331 @@ = { "total_rows": 3, "offset": 1, "rows": [ - {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}}, + {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}}, - {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}} + {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}} ] } }}} - = Use ''endkey'' if you are interested in a specific range of documents: = {{{ GET somedatabase/_all_docs?startkey=3D"doc2"&endkey=3D"doc3" HTTP/1.0 }}} - = This will get keys inbetween and including doc2 and doc3; e.g. ''doc2-b''= and ''doc234''. = Both approaches can be combined with ''descending'': @@ -396, +348 @@ {{{ GET somedatabase/_all_docs?startkey=3D"doc2"&limit=3D2&descending=3Dtrue = HTTP/1.0 }}} - = Will return: = {{{ @@ -407, +358 @@ = { "total_rows": 3, "offset": 1, "rows": [ - {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}} + {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}} - {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}}, + {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}}, ] } }}} - = If you add ''include_docs=3Dtrue'' to a request to ''_all_docs'' not only= metadata but also the documents themselves are returned. = =3D=3D all_docs_by_seq =3D=3D - = This allows you to see all the documents that were updated and deleted, i= n the order these actions are done: = {{{ GET somedatabase/_all_docs_by_seq HTTP/1.0 }}} - = Will return: = {{{ @@ -435, +383 @@ "total_rows": 4, "offset": 0, "rows": [ {"id": "doc1", "key": "1", "value": {"rev":"1-4124667444"}}, {"id": "doc2", "key": "2", "value": {"rev":"1-1815587255"}}, - {"id": "doc3", "key": "3", "value": {"rev": "1-1750227892"}}, + {"id": "doc3", "key": "3", "value": {"rev":"1-1750227892"}}, - {"id": "doc4", "key": "4", "value": {"rev": "2-524044848", "deleted":= true}} + {"id": "doc4", "key": "4", "value": {"rev":"2-524044848", "deleted": = true}} ] } }}} - = All the view parameters work on _all_docs_by_seq, such as startkey, inclu= de_docs etc. However, note that the startkey is exclusive when applied to t= his view. This allows for a usage pattern where the startkey is set to the = sequence id of the last doc returned by the previous query. As the startkey= is exclusive, the same document won't be processed twice. = - = =3D=3D Attachments =3D=3D - = Documents can have attachments just like email. There are two ways to use= attachments. The first one is inline with your document and it described f= irst. The second one is a separate REST API for attachments that is describ= ed a little further down. = - A note on attachment names: Attachments may have embedded '''/''' charact= ers that are sent unescaped to CouchDB. You can use this to provide a subtr= ee of attachments under a document. A DocID must have any '''/''' escaped a= s '''%2F'''. So if you have document ''a/b/c'' with an attachment ''d/e/f.t= xt'', you would be able to access it at http://couchdb/db/a%2fb%2fc/d/e/f.t= xt . + A note on attachment names: Attachments may have embedded '''/''' charact= ers that are sent unescaped to CouchDB. You can use this to provide a subtr= ee of attachments under a document. A DocID must have any '''/''' escaped a= s '''%2F'''. So if you have document ''a/b/c'' with an attachment ''d/e/f.t= xt'', you would be able to access it at [[http://couchdb/db/a/b/c/d/e/f.txt= |http://couchdb/db/a%2fb%2fc/d/e/f.txt]] . = =3D=3D=3D Inline Attachments =3D=3D=3D On creation, attachments go into a special ''_attachments'' attribute of = the document. They are encoded in a JSON structure that holds the name, the= content_type and the base64 encoded data of an attachment. A document can = have any number of attachments. = - When retrieving documents, the attachment's actual data is not included, = only the metadata. The actual data has to be fetched separately, using a sp= ecial URI. = + When retrieving documents, the attachment's actual data is not included, = only the metadata. The actual data has to be fetched separately, using a sp= ecial URI. = If you need to access attachments with the document in one request, you c= an pass in the `?attachments=3Dtrue` URL parameter to get the data included= in the JSON in the base64 encoded form. Since this puts a significant burd= en on CouchDB when you request this, you're not advised to use this feature= unless you know what you are doing :) = @@ -472, +417 @@ } } }}} - = Please note that any base64 data you send has to be on '''a single line o= f characters''', so pre-process your data to remove any carriage returns an= d newlines. = Requesting said document: @@ -480, +424 @@ {{{ GET /database/attachment_doc }}} - = CouchDB replies: = {{{ @@ -498, +441 @@ } } }}} - = Note that the ''"stub":true'' attribute denotes that this is not the comp= lete attachment. Also, note the length attribute added automatically. = Requesting the attachment: @@ -506, +448 @@ {{{ GET /database/attachment_doc/foo.txt }}} - = CouchDB returns: = {{{ This is a base64 encoded text }}} - = Automatically decoded! = =3D=3D=3D Multiple Attachments =3D=3D=3D - = Creating a document with an attachment: = {{{ @@ -538, +477 @@ } } }}} - = - = =3D=3D=3D Standalone Attachments =3D=3D=3D - = Note: This was added in version 0.9 of CouchDB. It is not available in ea= rlier version. = CouchDB allows to create, change and delete attachments without touching = the actual document. As a bonus feature, you do not have to base64 encode y= our data. This can significantly speed up requests since CouchDB and your c= lient do not have to do the base64 conversion. @@ -549, +485 @@ You need to specify a MIME type using the Content-Type header. CouchDB wi= ll serve the attachment with the specified Content-Type when asked. = To create an attachment: + = {{{ PUT somedatabase/document/attachment?rev=3D123 HTTP/1.0 Content-Length: 245 @@ -556, +493 @@ = }}} - = CouchDB replies: + = {{{ {"ok": true, "id": "document", "rev": "765B7D1C"} }}} - = Note that you can do this on a non-existing document. The document and at= tachment will be created implicitly for you. A revision id must not be spec= ified in this case. = To change an attachment: + = {{{ PUT somedatabase/document/attachment?rev=3D765B7D1C HTTP/1.0 Content-Length: 245 @@ -572, +509 @@ = }}} - = CouchDB replies: + = {{{ {"ok": true, "id": "document", "rev": "766FC88G"} }}} - = To delete an attachment: = {{{ DELETE somedatabase/document/attachment?rev=3D765B7D1C HTTP/1.0 }}} - = CouchDB replies: + = {{{ {"ok":true,"id":"document","rev":"519558700"} }}} - = To retrieve an attachment: = {{{ GET somedatabase/document/attachment HTTP/1.0 }}} - = CouchDB replies + = {{{ Content-Type:image/jpeg = }}} - = - = =3D=3D ETags/Caching =3D=3D - = CouchDB sends an ''ETag'' Header for document requests. The ETag Header i= s simply the document's revision in quotes. = For example, a ''GET'' request: @@ -612, +544 @@ {{{ GET /database/123182719287 }}} - = Results in a reply with the following headers: = {{{ @@ -623, +554 @@ content-type: text/plain;charset=3Dutf-8 etag: "615790463" }}} - = ''POST'' requests also return an ''ETag'' header for either newly created= or updated documents. =20