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 RandallLeeds
Date Tue, 27 Oct 2009 21:41:34 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 RandallLeeds.
The comment on this change is: A few _revs where there should be no underscore.
http://wiki.apache.org/couchdb/HTTP_Document_API?action=diff&rev1=55&rev2=56

--------------------------------------------------

  This is an introduction to the CouchDB HTTP document API.
  
  == Naming/Addressing ==
- 
  Documents stored in a CouchDB have a DocID. DocIDs are case-sensitive string identifiers
that uniquely identify a document. Two documents cannot have the same identifier in the same
database, they are considered the same document.
  
  {{{
@@ -11, +10 @@

  http://localhost:5984/test/another_doc_id
  http://localhost:5984/test/BA1F48C5418E4E68E5183D5BD1F06476
  }}}
- 
  The above URLs point to ''some_doc_id'', ''another_doc_id'' and ''BA1F48C5418E4E68E5183D5BD1F06476''
in the database ''test''.
  
  == Documents ==
- 
  A CouchDB document is simply a JSON object. You can use any JSON structure with nesting.
You can fetch the document's revision information by adding ''?revs=true'' or ''?revs_info=true''
to the get request.
  
  Here are two simple examples of documents:
+ 
  {{{
  {
   "_id":"discussion_tables",
@@ -32, +30 @@

   ]
  }
  }}}
- 
- 
  {{{
  {
   "_id":"some_doc_id",
@@ -45, +41 @@

   "Body":"I decided today that I don't like baseball. I like plankton."
  }
  }}}
- 
  === Special Fields ===
  Note that any top-level fields with a name that starts with a ''_'' prefix are reserved
for use by CouchDB itself. Also see [[Reserved_words]]. Currently (0.10+) reserved fields
are:
  
@@ -58, +53 @@

   ''_conflicts'':: Information about conflicts
   ''_deleted_conflicts'':: Information about conflicts
  
- 
  ==== Document IDs ====
- 
  You can have '''/''' as part of the DocID but if you refer to a document in a URL you must
always encode it as '''%2F'''. One special case is '''_design/''' documents, those accept
either '''/''' or '''%2F''' for the '''/''' after ''_design'', although '''/''' is preferred
and %2F is still needed for the rest of the DocID.
  
  '''Q: What's the rule on a valid document id? The examples suggest it's restricted to ''[a-zA-Z0-9_]''?
What about multi-byte UTF-8 characters? Any other non alphanums other than ''_''?'''
@@ -69, +62 @@

  
  The reason database names have strict restrictions is to simplify database name-to-file
mapping. Since databases will need to replicate across operating systems, the file naming
scheme needed to be the lowest common denominator.
  
- 
  == Working With Documents Over HTTP ==
- 
  === GET ===
- 
  To retrieve a document, simply perform a ''GET'' operation at the document's URL:
  
  {{{
  GET /somedatabase/some_doc_id HTTP/1.0
  }}}
- 
  Here is the server's response:
  
  {{{
@@ -98, +87 @@

   "Body":"I decided today that I don't like baseball. I like plankton."
  }
  }}}
- 
  === Accessing Previous Revisions ===
- 
- See [[DocumentRevisions]] for additional notes on revisions.
+ See DocumentRevisions for additional notes on revisions.
  
  The above example gets the current revision. You may be able to get a specific revision
by using the following syntax:
  
  {{{
  GET /somedatabase/some_doc_id?rev=946B7D1C HTTP/1.0
  }}}
- 
  To find out what revisions are available for a document, you can do:
  
  {{{
  GET /somedatabase/some_doc_id?revs=true HTTP/1.0
  }}}
- 
  This returns the current revision of the document, but with an additional field, ''_revisions'',
the value being a list of the available revision IDs. ''Note though that not every of those
revisions of the document is necessarily still available.'' For example, the content of an
old revision get removed by compacting the database, or it may only exist in a different database
if it was replicated.
  
  To get more detailed information about the available document revisions, use the ''revs_info''
parameter instead. In this case, the JSON result will contain a ''_revs_info'' property, which
is an array of objects, for example:
@@ -128, +113 @@

    ]
  }
  }}}
- 
  Here, ''disk'' means the revision content is stored on disk and can still be retrieved.
The other values indicate that the content of that revision is not available.
  
  <<Anchor(create_or_update_document)>>
+ 
  === PUT ===
- 
  To create new document you can either use a ''POST'' operation or a ''PUT'' operation. To
create/update a named document using the PUT operation, the URL must point to the document's
location.
  
  The following is an example HTTP ''PUT''. It will cause the CouchDB server to generate a
new revision ID and save the document with it.
@@ -151, +135 @@

    "Body":"I decided today that I don't like baseball. I like plankton."
  }
  }}}
- 
  Here is the server's response.
  
  {{{
@@ -162, +145 @@

  
  {"ok": true, "id": "some_doc_id", "rev": "946B7D1C"}
  }}}
- 
  To update an existing document, you also issue a ''PUT'' request. In this case, the JSON
body must contain a ''_rev'' property, which lets CouchDB know which revision the edits are
based on. If the revision of the document currently stored in the database doesn't match,
then a ''409'' conflict error is returned.
  
  If the revision number does match what's in the database, a new revision number is generated
and returned to the client.
@@ -184, +166 @@

    "Body":"I decided today that I don't like baseball. I like plankton."
  }
  }}}
- 
  Here is the server's response if what is stored in the database is revision ''946B7D1C''
of document ''some_doc_id''.
  
  {{{
@@ -195, +176 @@

  
  {"ok":true, "id":"some_doc_id", "rev":"2774761002"}
  }}}
- 
  And here is the server's response if there is an update conflict (what is currently stored
in the database is not revision ''946B7D1C'' of document ''some_doc_id'').
  
  {{{
@@ -206, +186 @@

  
  {"error":"conflict","reason":"Document update conflict."}
  }}}
- 
- There is a query option ''batch=ok'' which can be used to achieve higher throughput at the
cost of lower guarantees. When a ''PUT'' (or a document ''POST'' as described below) is sent
using this option, it is not immediately written to disk. Instead it is stored in memory on
a per-user basis for a second or so (or the number of docs in memory reaches a certain point).
After the threshold has passed, the docs are committed to disk. Instead of waiting for the
doc to be written to disk before responding, CouchDB sends an HTTP ''202 Accepted'' response
immediately. 
+ There is a query option ''batch=ok'' which can be used to achieve higher throughput at the
cost of lower guarantees. When a ''PUT'' (or a document ''POST'' as described below) is sent
using this option, it is not immediately written to disk. Instead it is stored in memory on
a per-user basis for a second or so (or the number of docs in memory reaches a certain point).
After the threshold has passed, the docs are committed to disk. Instead of waiting for the
doc to be written to disk before responding, CouchDB sends an HTTP ''202 Accepted'' response
immediately.
  
  ''batch=ok'' is not suitable for crucial data, but it ideal for applications like logging
which can accept the risk that a small proportion of updates could be lost due to a crash.
Docs in the batch can also be flushed manually using the ''_ensure_full_commit'' API.
  
  === POST ===
- 
  The ''POST'' operation can be used to create a new document with a server generated DocID.
To create a named document, use the ''PUT'' method instead. It is recommended that you avoid
''POST'' when possible, because proxies and other network intermediaries will occasionally
resend ''POST'' requests, which can result in duplicate document creation. If your client
software is not capable of guaranteeing uniqueness of generated UUIDs, use a ''GET'' to ''/_uuids?count=100''
to retrieve a list of document IDs for future ''PUT'' requests. Please note that the ''/_uuids''-call
does not check for existing document ids; collision-detection happens when you are trying
to save a document.
  
  The following is an example HTTP ''POST''. It will cause the CouchDB server to generate
a new DocID and revision ID and save the document with it.
@@ -230, +208 @@

    "Body":"I decided today that I don't like baseball. I like plankton."
  }
  }}}
- 
  Here is the server's response:
  
  {{{
@@ -240, +217 @@

  Connection: close
  
  {"ok":true, "id":"123BAC", "rev":"946B7D1C"}
- 
  }}}
- 
- 
  === DELETE ===
- 
  To delete a document, perform a ''DELETE'' operation at the document's location, passing
the ''rev'' parameter with the document's current revision. If successful, it will return
the revision id for the deletion stub.
  
  {{{
  DELETE /somedatabase/some_doc?rev=1582603387 HTTP/1.0
  }}}
- 
  As an alternative you can submit the ''rev'' parameter with the etag header field ''If-Match''.
+ 
  {{{
  DELETE /somedatabase/some_doc HTTP/1.0
  If-Match: "1582603387"
  }}}
- 
  And the response:
  
  {{{
@@ -268, +240 @@

  
  {"ok":true,"rev":"2839830636"}
  }}}
- 
- 
  === COPY ===
- 
  Note that this is a non-standard extension to HTTP.
  
  You can copy documents by sending an HTTP COPY request. This allows you to duplicate the
contents (and attachments) of a document to a new document under a different document id without
first retrieving it from CouchDB. Use the ''Destination'' header to specify the document that
you want to copy to (the target document).
@@ -282, +251 @@

  COPY /somedatabase/some_doc HTTP/1.1
  Destination: some_other_doc
  }}}
- 
  If you want to overwrite an existing document, you need to specify the target document's
revision with a ''rev'' parameter in the ''Destination'' header:
  
  {{{
  COPY /somedatabase/some_doc HTTP/1.1
  Destination: some_other_doc?rev=rev_id
  }}}
- 
  The response in both cases includes the target document's revision:
  
  {{{
@@ -302, +269 @@

  Cache-Control: must-revalidate
  
  {"ok":true,"id":"some_other_doc","rev":"355068078"}
- 
  }}}
- 
- 
  === MOVE ===
- 
  For a ~6 month period CouchDB trunk between versions 0.8 and 0.9 included the nonstandard
MOVE method. Since MOVE is really just COPY & DELETE and CouchDB can not reasonably guarantee
atomicity between the COPY & MOVE operations on a single or on multiple nodes, this was
removed before the release of CouchDB 0.9.
-  
  
  === Bulk Docs ===
- 
  For information about editing multiple documents at the same time, see [[HTTP_Bulk_Document_API]]
  
- 
  == All Documents ==
- 
  To get a listing of all documents in a database, use the special ''_all_docs'' URI. This
is a specialized View so the Querying Options of the [[HTTP_view_API]] apply here.
  
- 
  {{{
  GET somedatabase/_all_docs HTTP/1.0
  }}}
- 
  Will return a listing of all documents and their revision IDs, ordered by DocID (case sensitive):
  
  {{{
@@ -341, +298 @@

    ]
  }
  }}}
- 
  Use the query argument ''descending=true'' to reverse the order of the output table:
  
  Will return the same as before but in reverse order:
@@ -354, +310 @@

  
  {
    "total_rows": 3, "offset": 0, "rows": [
-     {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}}
+     {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}}
-     {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}},
+     {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}},
-     {"id": "doc1", "key": "doc1", "value": {"_rev": "4324BB"}},
+     {"id": "doc1", "key": "doc1", "value": {"rev": "4324BB"}},
    ]
  }
  }}}
- 
  The query string parameters ''startkey'', ''endkey'' and ''limit'' may also be used to limit
the result set. For example:
  
  {{{
  GET somedatabase/_all_docs?startkey="doc2"&limit=2 HTTP/1.0
  }}}
- 
  Will return:
  
  {{{
@@ -377, +331 @@

  
  {
    "total_rows": 3, "offset": 1, "rows": [
-     {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}},
+     {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}},
-     {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}}
+     {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}}
    ]
  }
  }}}
- 
  Use ''endkey'' if you are interested  in a specific range of documents:
  
  {{{
  GET somedatabase/_all_docs?startkey="doc2"&endkey="doc3" HTTP/1.0
  }}}
- 
  This will get keys inbetween and including doc2 and doc3; e.g. ''doc2-b'' and ''doc234''.
  
  Both approaches can be combined with ''descending'':
@@ -396, +348 @@

  {{{
  GET somedatabase/_all_docs?startkey="doc2"&limit=2&descending=true HTTP/1.0
  }}}
- 
  Will return:
  
  {{{
@@ -407, +358 @@

  
  {
    "total_rows": 3, "offset": 1, "rows": [
-     {"id": "doc3", "key": "doc3", "value": {"_rev":"74EC24"}}
+     {"id": "doc3", "key": "doc3", "value": {"rev":"74EC24"}}
-     {"id": "doc2", "key": "doc2", "value": {"_rev":"2441HF"}},
+     {"id": "doc2", "key": "doc2", "value": {"rev":"2441HF"}},
    ]
  }
  }}}
- 
  If you add ''include_docs=true'' to a request to ''_all_docs'' not only metadata but also
the documents themselves are returned.
  
  == all_docs_by_seq ==
- 
  This allows you to see all the documents that were updated and deleted, in the order these
actions are done:
  
  {{{
  GET somedatabase/_all_docs_by_seq HTTP/1.0
  }}}
- 
  Will return:
  
  {{{
@@ -435, +383 @@

    "total_rows": 4, "offset": 0, "rows": [
      {"id": "doc1", "key": "1", "value": {"rev":"1-4124667444"}},
      {"id": "doc2", "key": "2", "value": {"rev":"1-1815587255"}},
-     {"id": "doc3", "key": "3", "value": {"rev": "1-1750227892"}},
+     {"id": "doc3", "key": "3", "value": {"rev":"1-1750227892"}},
-     {"id": "doc4", "key": "4", "value": {"rev": "2-524044848", "deleted": true}}
+     {"id": "doc4", "key": "4", "value": {"rev":"2-524044848", "deleted": true}}
    ]
  }
  }}}
- 
  All the view parameters work on _all_docs_by_seq, such as startkey, include_docs etc. However,
note that the startkey is exclusive when applied to this view. This allows for a usage pattern
where the startkey is set to the sequence id of the last doc returned by the previous query.
As the startkey is exclusive, the same document won't be processed twice.
  
- 
  == 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.
  
- 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%2fb%2fc/d/e/f.txt
.
+ 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]]
.
  
  === 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, only the metadata.
The actual data has to be fetched separately, using a special URI. 
+ 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 :)
  
@@ -472, +417 @@

    }
  }
  }}}
- 
  Please note that any base64 data you send has to be on '''a single line of characters''',
so pre-process your data to remove any carriage returns and newlines.
  
  Requesting said document:
@@ -480, +424 @@

  {{{
  GET /database/attachment_doc
  }}}
- 
  CouchDB replies:
  
  {{{
@@ -498, +441 @@

    }
  }
  }}}
- 
  Note that the ''"stub":true'' attribute denotes that this is not the complete attachment.
Also, note the length attribute added automatically.
  
  Requesting the attachment:
@@ -506, +448 @@

  {{{
  GET /database/attachment_doc/foo.txt
  }}}
- 
  CouchDB returns:
  
  {{{
  This is a base64 encoded text
  }}}
- 
  Automatically decoded!
  
  === Multiple Attachments ===
- 
  Creating a document with an attachment:
  
  {{{
@@ -538, +477 @@

    }
  }
  }}}
- 
- 
  === Standalone Attachments ===
- 
  Note: This was added in version 0.9 of CouchDB. It is not available in earlier version.
  
  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.
@@ -549, +485 @@

  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:
+ 
  {{{
  PUT somedatabase/document/attachment?rev=123 HTTP/1.0
  Content-Length: 245
@@ -556, +493 @@

  
  <JPEG data>
  }}}
- 
  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
@@ -572, +509 @@

  
  <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>
  }}}
- 
- 
  == ETags/Caching ==
- 
  CouchDB sends an ''ETag'' Header for document requests. The ETag Header is simply the document's
revision in quotes.
  
  For example, a ''GET'' request:
@@ -612, +544 @@

  {{{
  GET /database/123182719287
  }}}
- 
  Results in a reply with the following headers:
  
  {{{
@@ -623, +554 @@

  content-type: text/plain;charset=utf-8
  etag: "615790463"
  }}}
- 
  ''POST'' requests also return an ''ETag'' header for either newly created or updated documents.
  

Mime
View raw message