couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Couchdb Wiki] Update of "HTTP_Document_API" by JensAlfke
Date Wed, 21 Dec 2011 00:24:11 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "HTTP_Document_API" page has been changed by JensAlfke:
http://wiki.apache.org/couchdb/HTTP_Document_API?action=diff&rev1=86&rev2=87

Comment:
Added documentation of PUTting docs with attachments in multipart/related format.

  }
  }}}
  
+ Alternatively, you can upload a document with attachments more efficiently in [[http://tools.ietf.org/html/rfc2387|MIME
multipart/related]] format. This avoids having to Base64-encode the attachments, saving CPU
and bandwidth. To do this, set the "Content-Type" header of the PUT request to "multipart/related".

+ 
+  * The first MIME body is the document itself, which should have its own Content-Type of
"application/json". It should include an `_attachments` metadata object in which each attachment
object has a key `follows` with value `true`.
+ 
+  * The subsequent MIME bodies are the attachments. As of this writing (Dec. 2011) CouchDB
ignores headers and identifies the attachments only by their order (corresponding to the order
in which the metadata objects appear in the `_attachments` object.) This can be problematic
as few non-Erlang JSON 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="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--
+ }}}
+ 
  === Getting Attachments With a Document ===
  
  If you need to fetch a document and all its attachments in one request, add an `?attachments=true`
URL parameter to the GET request. The resulting JSON will include the base64-encoded contents
in the "data" property of each 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 middle 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, just add an "Accept:" header to the request with value "multipart/related". (You still
need the `?attachments=true` 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 easier to stream directly to disk (especially if your platform
has a MIME parsing library). To get this response format, just add an "Accept:" header to
the request with value "multipart/related". (You still need the `?attachments=true` parameter
too.)
  
  Unfortunately, at present (Dec. 2011) the multipart response has no headers on any of the
attachment bodies, so the only way to tell which one is which 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 parsers don't preserve the order of keys.
  

Mime
View raw message