From commits-return-32904-archive-asf-public=cust-asf.ponee.io@couchdb.apache.org Fri Apr 13 07:43:50 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 34276180627 for ; Fri, 13 Apr 2018 07:43:49 +0200 (CEST) Received: (qmail 4976 invoked by uid 500); 13 Apr 2018 05:43:48 -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 4967 invoked by uid 99); 13 Apr 2018 05:43:48 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd4-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 13 Apr 2018 05:43:48 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd4-us-west.apache.org (ASF Mail Server at spamd4-us-west.apache.org) with ESMTP id C465DC030C for ; Fri, 13 Apr 2018 05:43:47 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd4-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -10.311 X-Spam-Level: X-Spam-Status: No, score=-10.311 tagged_above=-999 required=6.31 tests=[ENV_AND_HDR_SPF_MATCH=-0.5, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, T_RP_MATCHES_RCVD=-0.01, USER_IN_DEF_SPF_WL=-7.5] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd4-us-west.apache.org [10.40.0.11]) (amavisd-new, port 10024) with ESMTP id mGKw4RECNSDc for ; Fri, 13 Apr 2018 05:43:43 +0000 (UTC) Received: from mailrelay1-us-west.apache.org (mailrelay1-us-west.apache.org [209.188.14.139]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTP id 229CC5F126 for ; Fri, 13 Apr 2018 05:43:43 +0000 (UTC) Received: from moin-vm.apache.org (moin-vm.apache.org [163.172.69.106]) by mailrelay1-us-west.apache.org (ASF Mail Server at mailrelay1-us-west.apache.org) with ESMTP id 23065E0117 for ; Fri, 13 Apr 2018 05:43:42 +0000 (UTC) Received: from moin-vm.apache.org (localhost [IPv6:::1]) by moin-vm.apache.org (ASF Mail Server at moin-vm.apache.org) with ESMTP id 69E6D80111 for ; Fri, 13 Apr 2018 07:43:41 +0200 (CEST) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable From: Apache Wiki To: Apache Wiki Date: Fri, 13 Apr 2018 05:43:41 -0000 Message-ID: <152359822143.23107.13595795695474748807@moin-vm.apache.org> Subject: =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22HttpDocumentApi=22_by_JoanTouze?= =?utf-8?q?t?= Auto-Submitted: auto-generated Dear wiki user, You have subscribed to a wiki page "Couchdb Wiki" for change notification. The page "HttpDocumentApi" has been deleted by JoanTouzet: https://wiki.apache.org/couchdb/HttpDocumentApi?action=3Ddiff&rev1=3D33&rev= 2=3D34 - #redirect HTTP_Document_API - 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. - = - {{{ - http://localhost:5984/test/some_doc_id - 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= 5418E4E68E5183D5B!D1F06476'' in the database ''test''. - = - =3D=3D=3D Valid Document Ids =3D=3D=3D - = - Q: What's the rule on a valid document id? The examples suggest it's re= stricted to ''[a-zA-Z0-9_]''? What about multi-byte UTF-8 characters? Any o= ther non alphanums other than ''_''? - = - A: There is no restriction yet on document ids at the database level. H= owever, I haven't tested what happens when you try to use multibyte in the = URL. It could be it "just works", but most likely there is a multi-byte cha= r escaping/encoding/decoding step that needs to be done somewhere. For now,= I'd just stick with valid URI characters and nothing "special". - = - The reason database names have strict restrictions is to simplify datab= ase name-to-file mapping. Since databases will need to replicate across ope= rating systems, the file naming scheme needed to be the lowest common denom= inator. - = - =3D=3D JSON =3D=3D - = - A CouchDB document is simply a JSON object. (Along with metadata revision= info if ''?full=3Dtrue'' is in the URL query arguments. - = - This is an example document: - = - {{{ - { - "_id":"discussion_tables", - "_rev":"D1C946B7", - "Subject":"I like Plankton", - "Author":"Rusty", - "PostedDate":"2006-08-15T17:30:12-04:00", - "Tags":["plankton", "baseball", "decisions"], - "Body":"I decided today that I don't like baseball. I like plankton." - } - }}} - = - The document can be an arbitrary JSON object, but note that any top-level= fields with a name that starts with a ''_'' prefix are reserved for use by= CouchDB itself. Common examples for such fields are ''_id'' and ''_rev'', = as shown above. - = - Another example: - = - {{{ - { - "_id":"discussion_tables", - "_rev":"D1C946B7", - "Subrise":true, - "Sunset":false, - "FullHours":[1,2,3,4,5,6,7,8,9,10], - "Activities": [ - {"Name":"Football", "Duration":2, "DurationUnit":"Hours"}, - {"Name":"Breakfast", "Duration":40, "DurationUnit":"Minutes", "Attende= es":["Jan", "Damien", "Laura", "Gwendolyn", "Roseanna"]} - ] - } - }}} - = - Note that by default the structure is flat; in this case, the ''Activitie= s'' attribute is structure imposed by the user. - = - =3D=3D All Documents =3D=3D - = - To get a listing of all documents in a database, use the special ''_all_d= ocs'' URI: - = - {{{ - GET somedatabase/_all_docs HTTP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - Will return a listing of all documents and their revision IDs, ordered by= DocID (case sensitive): - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - { - "total_rows": 3, "offset": 0, "rows": [ - {"id": "doc1", "key": "doc1", "value": {"rev": "4324BB"}}, - {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}}, - {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}} - ] - } - }}} - = - Use the query argument ''descending=3Dtrue'' to reverse the order of the = output table: - = - Will return the same as before but in reverse order: - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - { - "total_rows": 3, "offset": 0, "rows": [ - {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}} - {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}}, - {"id": "doc1", "key": "doc1", "value": {"_rev": "4324BB"}}, - ] - } - }}} - = - The query string parameters ''startkey'' and ''count'' may also be used t= o limit the result set. For example: - = - {{{ - GET somedatabase/_all_docs?startkey=3Ddoc2&count=3D2 HTTP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - Will return: - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - { - "total_rows": 3, "offset": 1, "rows": [ - {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}}, - {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}} - ] - } - }}} - = - And combined with ''descending'': - = - {{{ - GET somedatabase/_all_docs?startkey=3Ddoc2&count=3D2&descending=3Dtrue HT= TP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - Will return: - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - { - "total_rows": 3, "offset": 1, "rows": [ - {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}} - {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}}, - ] - } - }}} - = - =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 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - Here is the server's response: - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - { - "_id":"123BAC", - "_rev":"946B7D1C", - "Subject":"I like Planktion", - "Author":"Rusty", - "PostedDate":"2006-08-15T17:30:12Z-04:00", - "Tags":["plankton", "baseball", "decisions"], - "Body":"I decided today that I don't like baseball. I like plankton." - } - }}} - = - =3D=3D=3D Accessing Previous Revisions =3D=3D=3D - = - See [[DocumentRevisions]]=01 for additional notes on revisions. - = - The above example gets the current revision. You can get a specific revis= ion by using the following syntax: - = - {{{ - GET /somedatabase/some_doc_id?rev=3D946B7D1C HTTP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - To find out what revisions are available for a document, you can do: - = - {{{ - GET /somedatabase/some_doc_id?revs=3Dtrue HTTP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - This returns the current revision of the document, but with an additional= field, ''_revs'', the value being a list of the available revision IDs. No= te though that not every of those revisions of the document is necessarily = still stored on disk. For example, the content of an old revision may 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: - = - {{{ - { - "_revs_info": [ - {"rev": "123456", "status": "disk"}, - {"rev": "234567", "status": "missing"}, - {"rev": "345678", "status": "deleted"}, - ] - } - }}} - = - 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. - = - {{{ - PUT /somedatabase/some_doc_id HTTP/1.0 - Content-Length: 245 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - = - { - "Subject":"I like Planktion", - "Author":"Rusty", - "PostedDate":"2006-08-15T17:30:12-04:00", - "Tags":["plankton", "baseball", "decisions"], - "Body":"I decided today that I don't like baseball. I like plankton." - } - }}} - = - Here is the server's response. - = - {{{ - HTTP/1.1 201 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - {"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. - = - For example: - = - {{{ - PUT /somedatabase/some_doc_id HTTP/1.0 - Content-Length: 245 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - = - { - "_id":"some_doc_id", - "_rev":"946B7D1C", - "Subject":"I like Planktion", - "Author":"Rusty", - "PostedDate":"2006-08-15T17:30:12-04:00", - "Tags":["plankton", "baseball", "decisions"], - "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''. - = - {{{ - HTTP/1.1 201 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - {"ok":true, "id":"some_doc_id", "rev":"946B7D1C"} - }}} - = - 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''). - = - {{{ - HTTP/1.1 409 CONFLICT - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Length: 33 - Connection: close - = - {"error":{"id":"conflict","reason":"3073715634"}} - }}} - = - =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 generating cryptographically secure UUIDs, use a ''POST'= ' to ''/_uuids?count=3D100'' to retrieve a list of unused document IDs for = future ''PUT'' requests. - = - 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. - = - {{{ - POST /somedatabase/ HTTP/1.0 - Content-Length: 245 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - = - { - "Subject":"I like Planktion", - "Author":"Rusty", - "PostedDate":"2006-08-15T17:30:12-04:00", - "Tags":["plankton", "baseball", "decisions"], - "Body":"I decided today that I don't like baseball. I like plankton." - } - }}} - = - Here is the server's response: - = - {{{ - HTTP/1.1 201 Created - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - {"ok":true, "id":"123BAC", "rev":"946B7D1C"} - }}} - = - =3D=3D=3D Modify Multiple Documents With a Single Request =3D=3D=3D - = - CouchDB provides a bulk insert/update feature. To use this, you make a ''= POST'' request to the URI ''/{dbname}/_bulk_docs'', with the request body b= eing a JSON document containing a list of new documents to be inserted or u= pdated. The bulk post is a transactional operation - all updates/insertions= succeed, or all fail. = - = - Doc formats below are as per CouchDB 0.8.0. - = - {{{ - { - "docs": [ - {"_id": "0", "integer": 0, "string": "0"}, - {"_id": "1", "integer": 1, "string": "1"}, - {"_id": "2", "integer": 2, "string": "2"} - ] - } - }}} - = - If you omit the per-document ''_id'' specification, CouchDB will generate= unique IDs for you, as it does for regular ''POST'' requests to the databa= se URI. - = - The response to such a bulk request would look as follows: - = - {{{ - { - "ok":true, - "new_revs": [ - {"id": "0", "rev": "3682408536"}, - {"id": "1", "rev": "3206753266"}, - {"id": "2", "rev": "426742535"} - ] - } - }}} - = - Updating existing documents requires setting the ''_rev'' member to the r= evision being updated. To delete a document set the ''_deleted'' member to = true. - = - {{{ - { - "docs": [ - {"_id": "0", "_rev": "3682408536", "_deleted": true}, - {"_id": "1", "_rev": "3206753266", "integer": 2, "string": "2"}, - {"_id": "2", "_rev": "426742535", "integer": 3, "string": "3"} - ] - } - }}} - = - Note that CouchDB will return in the response an id and revision for ever= y document passed as content to a bulk insert, even for those that were jus= t deleted. - = - =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 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - As an alternative you can submit the ''rev'' parameter with the etag head= er field ''If-Match''. - {{{ - DELETE /somedatabase/some_doc HTTP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - If-Match: "1582603387" - }}} - = - And the response: - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Type: application/json - Connection: close - = - {"ok":true,"rev":"2839830636"} - }}} - = - =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. - = - =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. - = - Creating a document with an attachment: - = - {{{ - { - "_id":"attachment_doc", - "_attachments": - { - "foo.txt": - { - "content_type":"text\/plain", - "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ=3D" - } - } - } - }}} - = - 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: - = - {{{ - GET /database/attachment_doc - }}} - = - CouchDB replies: - = - {{{ - { - "_id":"attachment_doc", - "_rev":1589456116, - "_attachments": - { - "foo.txt": - { - "stub":true, - "content_type":"text\/plain", - "length":29 - } - } - } - }}} - = - 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: - = - {{{ - 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: - = - {{{ - { - "_id":"attachment_doc", - "_attachments": - { - "foo.txt": - { - "content_type":"text\/plain", - "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ=3D" - }, - = - "bar.txt": - { - "content_type":"text\/plain", - "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ=3D" - } - } - } - }}} - = - = - =3D=3D=3D Standalone Attachments =3D=3D=3D - 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. - = - 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 - Content-Type: image/jpeg - = - - }}} - = - 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 - Content-Type: image/jpeg - = - - }}} - = - 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: - = - {{{ - GET /database/123182719287 - }}} - = - Results in a reply with the following headers: - = - {{{ - cache-control: no-cache, - pragma: no-cache - expires: Tue, 13 Nov 2007 23:09:50 GMT - transfer-encoding: chunked - content-type: text/plain;charset=3Dutf-8 - etag: "615790463" - }}} - = - ''POST'' requests also return an ''ETag'' header for either newly created= or updated documents. -=20