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:
