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 Sun, 28 Feb 2010 18:01:42 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: Cosmetic work; added table about special document ids.
http://wiki.apache.org/couchdb/HTTP_Document_API?action=diff&rev1=58&rev2=59

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

+ = HTTP Document API =
+ <<TableOfContents(3)>>
  This is an introduction to the CouchDB HTTP document API.
  
  == Naming/Addressing ==
@@ -44, +46 @@

  === 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:
  
+   ||'''Field Name'''||'''Description'''||
-  ''_id'':: The unique identifier of the document ('''mandatory''')
+   ||''_id''|| The unique identifier of the document ('''mandatory''' and '''immutable''')||
-  ''_rev'':: The current revision of this document ('''mandatory''')
+   ||''_rev''|| The current MVCC-token/revision of this document ('''mandatory''' and '''immutable''')||
-  ''_attachments'':: If the document has attachments, _attachments holds a (meta-)data structure
(see section on attachments)
+   ||''_attachments''|| If the document has attachments, _attachments holds a (meta-)data
structure (see section on [[HTTP_Document_API#Attachments||attachments]])||
-  ''_deleted'':: Indicates that this document has been deleted and will be removed on next
compaction run
+   ||''_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
+   ||''_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
+   ||''_rev_infos''|| Similar to ''_revisions'', but more details about the history and the
availability of ancient versions of the document||
-  ''_conflicts'':: Information about conflicts
+   ||''_conflicts''|| Information about conflicts||
-  ''_deleted_conflicts'':: Information about conflicts
+   ||''_deleted_conflicts''|| Information about conflicts||
  
  ==== Document IDs ====
+ Document IDs don't have restrictions on what characters can be used. Although it should
work, it is recommended to use non-special characters for document IDs. Using special characters
you have to be aware of proper URL en-/decoding. Documents prefixed with ''_'' are special
documents:
+ 
+   ||'''Document ID prefix'''||'''Description'''||
+   ||''_design/''|| are [[DesignDocuments]] ||
+   ||''_local/''|| are not being replicated (local documents) and used for [[Replication||replication]]
checkpointing. ||
+ 
- 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.
+ You can have '''/''' as part of the document ID 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 ==
  === GET ===
@@ -87, +90 @@

   "Body":"I decided today that I don't like baseball. I like plankton."
  }
  }}}
- === Accessing Previous Revisions ===
+ ==== Accessing Previous 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:

Mime
View raw message