From commits-return-7654-apmail-couchdb-commits-archive=couchdb.apache.org@couchdb.apache.org Wed Dec 21 00:24:33 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 AF81991B5 for ; Wed, 21 Dec 2011 00:24:33 +0000 (UTC) Received: (qmail 85604 invoked by uid 500); 21 Dec 2011 00:24:33 -0000 Delivered-To: apmail-couchdb-commits-archive@couchdb.apache.org Received: (qmail 85559 invoked by uid 500); 21 Dec 2011 00:24:33 -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 85541 invoked by uid 500); 21 Dec 2011 00:24:33 -0000 Delivered-To: apmail-incubator-couchdb-commits@incubator.apache.org Received: (qmail 85528 invoked by uid 99); 21 Dec 2011 00:24:33 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 21 Dec 2011 00:24:33 +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; Wed, 21 Dec 2011 00:24:32 +0000 Received: from eos.apache.org (localhost [127.0.0.1]) by eos.apache.org (Postfix) with ESMTP id E53DEB4C; Wed, 21 Dec 2011 00:24:11 +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: Wed, 21 Dec 2011 00:24:11 -0000 Message-ID: <20111221002411.16779.83108@eos.apache.org> Subject: =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22HTTP=5FDocument=5FAPI=22_by_Jen?= =?utf-8?q?sAlfke?= Auto-Submitted: auto-generated 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 JensAlfke: http://wiki.apache.org/couchdb/HTTP_Document_API?action=3Ddiff&rev1=3D86&re= v2=3D87 Comment: Added documentation of PUTting docs with attachments in multipart/related f= ormat. } }}} = + Alternatively, you can upload a document with attachments more efficientl= y in [[http://tools.ietf.org/html/rfc2387|MIME multipart/related]] format. = This avoids having to Base64-encode the attachments, saving CPU and bandwid= th. To do this, set the "Content-Type" header of the PUT request to "multip= art/related". = + = + * The first MIME body is the document itself, which should have its own = Content-Type of "application/json". It should include an `_attachments` met= adata object in which each attachment object has a key `follows` with value= `true`. + = + * The subsequent MIME bodies are the attachments. As of this writing (De= c. 2011) CouchDB ignores headers and identifies the attachments only by the= ir order (corresponding to the order in which the metadata objects appear i= n the `_attachments` object.) This can be problematic as few non-Erlang JSO= N encoders allow you to specify the order in which keys are written out. + = + Here's an HTTP request that uploads a document with two attachments: + = + {{{ + PUT /test_suite_db/multipart HTTP/1.1 + Content-Type: multipart/related;boundary=3D"abc123" + = + --abc123 + content-type: application/json + = + {"body":"This is a body.", + "_attachments":{ + "foo.txt": { + "follows":true, + "content_type":"text/plain", + "length":21 + }, + "bar.txt": { + "follows":true, + "content_type":"text/plain", + "length":20 + }, + } + } + = + --abc123 + = + this is 21 chars long + --abc123 + = + this is 20 chars lon + --abc123-- + }}} + = =3D=3D=3D Getting Attachments With a Document =3D=3D=3D = If you need to fetch a document and all its attachments in one request, a= dd an `?attachments=3Dtrue` URL parameter to the GET request. The resulting= JSON will include the base64-encoded contents in the "data" property of ea= ch attachment, just as in an inline upload. = - A more efficient way is to ask for a MIME multipart response. The benefit= is that the attachments are not base64-encoded, and they aren't in the mid= dle of the JSON so they're easier to stream directly to disk (especially if= your platform has a MIME parsing library). To get this response format, ju= st add an "Accept:" header to the request with value "multipart/related". (= You still need the `?attachments=3Dtrue` parameter too.) + A more efficient way is to ask for a [[http://tools.ietf.org/html/rfc2387= |MIME multipart/related]] response. The benefit is that the attachments are= not base64-encoded, and they aren't in the middle of the JSON so they're e= asier to stream directly to disk (especially if your platform has a MIME pa= rsing library). To get this response format, just add an "Accept:" header t= o the request with value "multipart/related". (You still need the `?attachm= ents=3Dtrue` parameter too.) = Unfortunately, at present (Dec. 2011) the multipart response has no heade= rs on any of the attachment bodies, so the only way to tell which one is wh= ich is to match them with the order of the keys in the JSON "_attachments" = object. This may not be easy in languages other than Erlang, as most JSON p= arsers don't preserve the order of keys. =20