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 SebastianCohnen
Date Sat, 24 Oct 2009 17:08:01 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 SebastianCohnen.
The comment on this change is: First approach to rewrite/restructure the bascis on couchdb
documents.
http://wiki.apache.org/couchdb/HTTP_Document_API?action=diff&rev1=53&rev2=54

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

- An introduction to the CouchDB HTTP document API.
+ This is an introduction to the CouchDB HTTP document API.
  
  == Naming/Addressing ==
  
@@ -14, +14 @@

  
  The above URLs point to ''some_doc_id'', ''another_doc_id'' and ''BA1F48C5418E4E68E5183D5BD1F06476''
in the database ''test''.
  
- === Valid Document Ids ===
+ == Documents ==
  
- 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.
+ 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:
-   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 ''_''?
- 
-   A: There is no restriction yet on document ids at the database level. However, I haven't
tested what happens when you try to use multibyte in the URL. It could be it "just works",
but most likely there is a multi-byte char escaping/encoding/decoding step that needs to be
done somewhere. For now, I'd just stick with valid URI characters and nothing "special".
- 
-   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.
- 
- == JSON ==
- 
- A CouchDB document is simply a JSON object. (Along with metadata revision info if ''?full=true''
is in the URL query arguments)
- 
- This is an example document:
- 
- {{{
- {
-  "_id":"some_doc_id",
-  "_rev":"D1C946B7",
-  "Subject":"I like Plankton",
-  "Author":"Rusty",
-  "PostedDate":"2006-08-15T17:30:12-04:00",
-  "Tags":["plankton", "baseball", "decisions"],
-  "Body":"I decided today that I don't like baseball. I like plankton."
- }
- }}}
- 
- The document can be an arbitrary JSON object, but note that any top-level fields with a
name that starts with a ''_'' prefix are reserved for use by CouchDB itself. Common examples
for such fields are ''_id'' and ''_rev'', as shown above.
- 
- Another example:
- 
  {{{
  {
   "_id":"discussion_tables",
@@ -60, +33 @@

  }
  }}}
  
- Note that by default the structure is flat; in this case, the ''Activities'' attribute is
structure imposed by the user.
  
+ {{{
+ {
+  "_id":"some_doc_id",
+  "_rev":"D1C946B7",
+  "Subject":"I like Plankton",
+  "Author":"Rusty",
+  "PostedDate":"2006-08-15T17:30:12-04:00",
+  "Tags":["plankton", "baseball", "decisions"],
+  "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. Currently (0.10+) reserved fields are:
+ 
+  ''_id'':: The unique identifier of the document ('''mandatory''')
+  ''_rev'':: The current revision of this document ('''mandatory''')
+  ''_attachments'':: If the document has attachments, _attachments holds a (meta-)data structure
(see section on attachments)
+  ''_deleted'':: Indicates that this document has been deleted and will be removed on next
compaction run
+  ''_revisions'':: If the document was requested with ''?revs=true'' this field will hold
a simple list of the documents history
+  ''_rev_infos'':: Similar to ''_revisions'', but more details about the history and the
availability of ancient versions of the document
+  ''_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 ''_''?'''
+ 
+ A: There is no restriction yet on document ids at the database level. However, I haven't
tested what happens when you try to use multibyte in the URL. It could be it "just works",
but most likely there is a multi-byte char escaping/encoding/decoding step that needs to be
done somewhere. For now, I'd just stick with valid URI characters and nothing "special".
+ 
+ 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 ==

Mime
View raw message