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 ==
