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:05:09 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=85&rev2=86

Comment:
Restructured attachment description. Added documentation of GETting attachments as multipart/related.

  See [[HTTP_database_API#Changes|/database/_changes]] for more details.
  
  == Attachments ==
- 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 first. The second one is a separate
REST API for attachments that is described a little further down.
+ Documents can have attachments just like email. There are two ways to use attachments: the
first one is a REST API that addresses individual attachments by URLs; the second is inline
with your document.
  
  A note on attachment names: Attachments may have embedded '''/''' characters that are sent
unescaped to CouchDB. You can use this to provide a subtree of attachments under a document.
A DocID must have any '''/''' escaped as '''%2F'''. So if you have document ''a/b/c'' with
an attachment ''d/e/f.txt'', 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]]
.
  
@@ -519, +519 @@

  === Inline Attachments ===
  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 by default, only
the metadata. The actual data can be fetched by a GET to the attachment's URL as described
in the previous section.
- When retrieving documents, the attachment's actual data is not included, only the metadata.
The actual data has to be fetched separately, using a special URI.
- 
- If you need to access attachments with the document in one request, you can pass in the
`?attachments=true` URL parameter to get the data included in the JSON in the base64 encoded
form. Since this puts a significant burden on CouchDB when you request this, you're not advised
to use this feature unless you know what you are doing :)
  
  Creating a document with an attachment:
  
@@ -599, +597 @@

  }
  }}}
  
+ === 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.)
+ 
+ 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.
+ 
+ Needless to say, this type of request can lead to arbitrarily large responses and can be
expensive for the server. Don't use it unless you need to; if you only want one or two attachments,
use individual GETs to fetch them.
  
  === Compression of Attachments ===
  As of version 0.11, CouchDB, by default, will automatically compress certain attachment
types.  That is, based on the Content-Type header of the request CouchDB may perform compression
of the data.  This is done to reduce the amount of data being shuffled around during replication,
and in most cases 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 compression and therefore
reduce the network latency of the request.

Mime
View raw message