From commits-return-6706-apmail-couchdb-commits-archive=couchdb.apache.org@couchdb.apache.org Sat Jul 30 15:56:27 2011 Return-Path: X-Original-To: apmail-couchdb-commits-archive@www.apache.org Delivered-To: apmail-couchdb-commits-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 3129F7BB8 for ; Sat, 30 Jul 2011 15:56:27 +0000 (UTC) Received: (qmail 26032 invoked by uid 500); 30 Jul 2011 15:56:26 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 25955 invoked by uid 500); 30 Jul 2011 15:56:25 -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 25745 invoked by uid 500); 30 Jul 2011 15:56:25 -0000 Delivered-To: apmail-incubator-couchdb-commits@incubator.apache.org Received: (qmail 25742 invoked by uid 99); 30 Jul 2011 15:56:25 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 30 Jul 2011 15:56:25 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.131] (HELO eos.apache.org) (140.211.11.131) by apache.org (qpsmtpd/0.29) with ESMTP; Sat, 30 Jul 2011 15:56:22 +0000 Received: from eos.apache.org (localhost [127.0.0.1]) by eos.apache.org (Postfix) with ESMTP id 1C973C14; Sat, 30 Jul 2011 15:56:01 +0000 (UTC) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable From: Apache Wiki To: Apache Wiki Date: Sat, 30 Jul 2011 15:56:00 -0000 Message-ID: <20110730155600.97629.52587@eos.apache.org> Subject: =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22HTTP=5FDocument=5FAPI=22_by_Jan?= =?utf-8?q?Lehnardt?= Auto-Submitted: auto-generated X-Virus-Checked: Checked by ClamAV on apache.org 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 JanLehnardt: http://wiki.apache.org/couchdb/HTTP_Document_API?action=3Ddiff&rev1=3D76&re= v2=3D77 Comment: move inline attachments down 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/b/c/d/e/f.txt= |http://couchdb/db/a%2fb%2fc/d/e/f.txt]] . + = + = + =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 versions. + = + 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 on an existing document: + = + {{{ + PUT somedatabase/document/attachment?rev=3D123 HTTP/1.0 + Content-Length: 245 + Content-Type: image/jpeg + = + + }}} + Note: You'll need to include the "rev" query parameter if you're adding (= or updating) an attachment on an existing document. This is true anytime yo= u update a document. If you don't know the value of _rev on the document, y= ou can retreive it with a lightweight [[#HEAD|HEAD request]] or by GETing t= he whole document. + = + 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=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. @@ -522, +585 @@ } } }}} - =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 versions. = - 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 on an existing document: - = - {{{ - PUT somedatabase/document/attachment?rev=3D123 HTTP/1.0 - Content-Length: 245 - Content-Type: image/jpeg - = - - }}} - Note: You'll need to include the "rev" query parameter if you're adding (= or updating) an attachment on an existing document. This is true anytime yo= u update a document. If you don't know the value of _rev on the document, y= ou can retreive it with a lightweight [[#HEAD|HEAD request]] or by GETing t= he whole document. - = - 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=3D Compression of Attachments =3D=3D=3D As of version 0.11, CouchDB, by default, will automatically compress cert= ain attachment types. That is, based on the Content-Type header of the req= uest CouchDB may perform compression of the data. This is done to reduce t= he amount of data being shuffled around during replication, and in most cas= es it's probably what you want. However, if uploading large files (e.g. a = 200M CSV) you may want to tweak this configuration in order to avoid compre= ssion and therefore reduce the network latency of the request. =20