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 JanLehnardt
Date Sat, 30 Jul 2011 15:56:00 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 JanLehnardt:
http://wiki.apache.org/couchdb/HTTP_Document_API?action=diff&rev1=76&rev2=77

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 first. The second one is a separate
REST API for attachments that is described a little further down.
  
  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]]
.
+ 
+ 
+ === Standalone Attachments ===
+ Note: This was added in version 0.9 of CouchDB. It is not available in earlier 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 your data. This can significantly speed
up requests since CouchDB and your client do not have to do the base64 conversion.
+ 
+ You need to specify a MIME type using the Content-Type header. CouchDB will serve the attachment
with the specified Content-Type when asked.
+ 
+ To create an attachment on an existing document:
+ 
+ {{{
+ PUT somedatabase/document/attachment?rev=123 HTTP/1.0
+ Content-Length: 245
+ Content-Type: image/jpeg
+ 
+ <JPEG data>
+ }}}
+ 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 you update a document. If you don't
know the value of _rev on the document, you can retreive it with a lightweight [[#HEAD|HEAD
request]] or by GETing the whole document.
+ 
+ CouchDB replies:
+ 
+ {{{
+ {"ok": true, "id": "document", "rev": "765B7D1C"}
+ }}}
+ Note that you can do this on a non-existing document. The document and attachment will be
created implicitly for you. A revision id must not be specified in this case.
+ 
+ To change an attachment:
+ 
+ {{{
+ PUT somedatabase/document/attachment?rev=765B7D1C HTTP/1.0
+ Content-Length: 245
+ Content-Type: image/jpeg
+ 
+ <JPEG data>
+ }}}
+ CouchDB replies:
+ 
+ {{{
+ {"ok": true, "id": "document", "rev": "766FC88G"}
+ }}}
+ To delete an attachment:
+ 
+ {{{
+ DELETE somedatabase/document/attachment?rev=765B7D1C 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
+ 
+ <JPEG data>
+ }}}
  
  === 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.
@@ -522, +585 @@

    }
  }
  }}}
- === Standalone Attachments ===
- Note: This was added in version 0.9 of CouchDB. It is not available in earlier 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 your data. This can significantly speed
up requests since CouchDB and your client do not have to do the base64 conversion.
  
- You need to specify a MIME type using the Content-Type header. CouchDB will serve the attachment
with the specified Content-Type when asked.
- 
- To create an attachment on an existing document:
- 
- {{{
- PUT somedatabase/document/attachment?rev=123 HTTP/1.0
- Content-Length: 245
- Content-Type: image/jpeg
- 
- <JPEG data>
- }}}
- 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 you update a document. If you don't
know the value of _rev on the document, you can retreive it with a lightweight [[#HEAD|HEAD
request]] or by GETing the whole document.
- 
- CouchDB replies:
- 
- {{{
- {"ok": true, "id": "document", "rev": "765B7D1C"}
- }}}
- Note that you can do this on a non-existing document. The document and attachment will be
created implicitly for you. A revision id must not be specified in this case.
- 
- To change an attachment:
- 
- {{{
- PUT somedatabase/document/attachment?rev=765B7D1C HTTP/1.0
- Content-Length: 245
- Content-Type: image/jpeg
- 
- <JPEG data>
- }}}
- CouchDB replies:
- 
- {{{
- {"ok": true, "id": "document", "rev": "766FC88G"}
- }}}
- To delete an attachment:
- 
- {{{
- DELETE somedatabase/document/attachment?rev=765B7D1C 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
- 
- <JPEG data>
- }}}
  === 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