CouchDB API Server Document Methods

-Document API CallsMethodPathDescriptionPOST/db - Create a new document - GET/db/doc - Returns the latest revision of the document - HEAD/db/doc - Returns bare information in the HTTP Headers for the document - PUT/db/doc - Inserts a new document, or new version of an existing document - DELETE/db/doc - Deletes the document - COPY/db/doc - Copies the document - GET/db/doc/attachment - Gets the attachment of a document - PUT/db/doc/attachment - Adds an attachment of a document - DELETE/db/doc/attachment - Deletes an attachment of a document -

- -

- - <literal>POST /db</literal> - - - - - - -URL API POST /dbMethodPOST /dbRequest - JSON of the new document - Response - JSON with the committed document information - Admin Privileges RequirednoQuery ArgumentsArgumentbatchDescription - Allow document store request to be batched with others - OptionalyesTypestringSupported ValuesokEnableReturn Codes201 - Document has been created successfully - 409 - Conflict - a document with the specified document ID already - exists - - - - Create a new document in the specified database, using the - supplied JSON document structure. If the JSON structure includes - the _id field, then the document will be - created with the specified document ID. If the - _id field is not specified, a new unique ID - will be generated. - - - - For example, you can generate a new document with a generated UUID - using the following request: - - - -POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} - - - - The return JSON will specify the automatically enerated ID and - revision information: - - - -{ - "id" : "64575eef70ab90a2b8d55fc09e00440d", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} - - -

- - Specifying the Document ID - - - The document ID can be specified by including the - _id field in the JSON of the submitted - record. The following request will create the same document with - the ID FishStew: - - - -POST http://couchdb:5984/recipes/ -Content-Type: application/json - -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} - - - - The structure of the submitted document is as shown in the table - below: - - - - - - - - - CouchDB Document - FieldDescription_id (optional) - Document ID - _rev (optional) - Revision ID (when updating an existing document) -

- - - In either case, the returned JSON will specify the document ID, - revision ID, and status message: - - - -{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} - - -

- -

- - Batch Mode Writes - - - You can write documents to the database at a higher rate by - using the batch option. This collects document writes together - in memory (on a user-by-user basis) before they are committed to - disk. This increases the risk of the documents not being stored - in the event of a failure, since the documents are not written - to disk immediately. - - - - To use the batched mode, append the batch=ok - query argument to the URL of the PUT or - POST request. The CouchDB server will respond - with a 202 HTTP response code immediately. - - -

- -

- - Including Attachments - - - You can include one or more attachments with a given document by - incorporating the attachment information within the JSON of the - document. This provides a simpler alternative to loading - documents with attachments than making a separate call (see - ). - - - - - - - - - Document with Attachments - FieldDescription_id (optional) - Document ID - _rev (optional) - Revision ID (when updating an existing document) - _attachments (optional) - Document Attachment - filename - Attachment information - content_type - MIME Content type string - data - File attachment content, Base64 encoded -

- - - The filename will be the attachment name. For - example, when sending the JSON structure below: - - - -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "content-type" : "text/css", - "data" : "cCB7IGZvbnQtc2l6ZTogMTJwdDsgfQo=", - }, - }, -} - - - - The attachment styling.css can be accessed - using /recipes/FishStew/styling.css. For more - information on attachments, see - . - - - - The document data embedded in to the structure must be encoded - using base64. - - -

- -

- - <literal>GET /db/doc</literal> - - - - - - -URL API GET /db/docMethodGET /db/docRequest - None - Response - Returns the JSON for the document - Admin Privileges RequirednoQuery ArgumentsArgumentconflictsDescription - Returns the conflict tree for the document. - OptionalyesTypebooleanDefaultfalseSupported ValuestrueIncludes the revisionsArgumentrevDescription - Specify the revision to return - OptionalyesTypestringSupported ValuestrueIncludes the revisionsArgumentrevsDescription - Return a list of the revisions for the document - OptionalyesTypebooleanArgumentrevs_infoDescription - Return a list of detailed revision information for the - document - OptionalyesTypebooleanSupported ValuestrueIncludes the revisionsReturn Codes201 - Document created - 400 - The format of the request or revision was invalid - 404 - The specified document or revision cannot be found, or has been - deleted - 409 - Conflict - a document with the specified document ID already - exists - - - - Returns the specified doc from the specified - db. For example, to retrieve the document with - the id FishStew you would send the following - request: - - - -GET http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Accept: application/json - - - - The returned JSON is the JSON of the document, including the - document ID and revision number: - - - -{ - "_id" : "FishStew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Irish Fish Stew" -} - - - - Unless you request a specific revision, the latest revision of the - document will always be returned. - - -

- - Attachments - - - If the document includes attachments, then the returned - structure will contain a summary of the attachments associatd - with the document, but not the attachment data itself. - - - - The JSON for the returned document will include the - _attachments field, with one or more - attachment definitions. For example: - - - -{ - "_id" : "FishStew", - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" - "_attachments" : { - "styling.css" : { - "stub" : true, - "content-type" : "text/css", - "length" : 783426, - }, - }, -} - - - - The format of the returned JSON is shown in the table below: - - - - - - - - - Returned Document with Attachments - FieldDescription_id (optional) - Document ID - _rev (optional) - Revision ID (when updating an existing document) - _attachments (optional) - Document Attachment - filename - Attachment - content_type - MIME Content type string - length - Length (bytes) of the attachment data - revpos - Revision where this attachment exists - stub - Indicates whether the attachment is a stub -

- -

- - Getting a List of Revisions - - - You can obtain a list of the revisions for a given document by - adding the revs=true parameter to the request - URL. For example: - - - -GET http://couchdb:5984/recipes/FishStew?revs=true -Accept: application/json - - - - The returned JSON structure includes the original document, - including a _revisions structure that - includes the revision information: - - - -{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "title" : "Irish Fish Stew", - "_revisions" : { - "ids" : [ - "a1a9b39ee3cc39181b796a69cb48521c", - "7c4740b4dcf26683e941d6641c00c39d", - "9c65296036141e575d32ba9c034dd3ee" - ], - "start" : 3 - }, - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -} - - - - - - - - - Returned CouchDB Document with Revision Info - FieldDescription_id (optional) - Document ID - _rev (optional) - Revision ID (when updating an existing document) - _revisions - CouchDB Document Revisions - ids [array] - Array of valid revision IDs, in reverse order (latest first) - start - Prefix number for the latest revision -

- -

- - Obtaining an Extended Revision History - - - You can get additional information about the revisions for a - given document by supplying the revs_info - argument to the query: - - - -GET http://couchdb:5984/recipes/FishStew?revs_info=true -Accept: application/json - - - - This returns extended revision information, including the - availability and status of each revision: - - - -{ - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "_id" : "FishStew", - "_revs_info" : [ - { - "status" : "available", - "rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" - }, - { - "status" : "available", - "rev" : "2-7c4740b4dcf26683e941d6641c00c39d" - }, - { - "status" : "available", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" - } - ], - "title" : "Irish Fish Stew", - "_rev" : "3-a1a9b39ee3cc39181b796a69cb48521c" -} - - - - - - - - - Returned CouchDB Document with Detailed Revision Info - FieldDescription_id (optional) - Document ID - _rev (optional) - Revision ID (when updating an existing document) - _revs_info [array] - CouchDB Document Extended Revision Info - rev - Full revision string - status - Status of the revision -

- -

- - Obtaining a Specific Revision - - - To get a specific revision, use the rev - argument to the request, and specify the full revision number: - - - -GET http://couchdb:5984/recipes/FishStew?rev=2-7c4740b4dcf26683e941d6641c00c39d -Accept: application/json - - - - The specified revision of the document will be returned, - including a _rev field specifying the - revision that was requested: - - - -{ - "_id" : "FishStew", - "_rev" : "2-7c4740b4dcf26683e941d6641c00c39d", - "servings" : 4, - "subtitle" : "Delicious with a green salad", - "title" : "Fish Stew" -} - - -

- -

- - <literal>HEAD /db/doc</literal> - - - - - -URL API HEAD /db/docMethodHEAD /db/docRequest - None - Response - None - Admin Privileges RequirednoQuery ArgumentsArgumentrevDescription - Specify the revision to return - OptionalyesTypestringArgumentrevsDescription - Return a list of the revisions for the document - OptionalyesTypebooleanArgumentrevs_infoDescription - Return a list of detailed revision information for the - document - OptionalyesTypebooleanReturn Codes404 - The specified document or revision cannot be found, or has been - deleted - - - - Returns the HTTP Headers containing a minimal amount of - information about the specified document. The method supports the - same query arguments as the GET method, but - only the header information (including document size, and the - revision as an ETag), is returned. For example, a simple - HEAD request: - - - -HEAD http://couchdb:5984/recipes/FishStew -Content-Type: application/json - - - - Returns the following HTTP Headers: - - - -HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Etag: "7-a19a1a5ecd946dad70e85233ba039ab2" -Date: Fri, 05 Nov 2010 14:54:43 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 136 -Cache-Control: must-revalidate - - - - The Etag header shows the current revision for - the requested document, and the Content-Length - specifies the length of the data, if the document were requested - in full. - - - - Adding any of the query arguments (as supported by - GET - method), then the resulting HTTP Headers will correspond to what - would be returned. Note that the current revision is not returned - when the refs_info argument is used. For - example: - - - -HTTP/1.1 200 OK -Server: CouchDB/1.0.1 (Erlang OTP/R13B) -Date: Fri, 05 Nov 2010 14:57:16 GMT -Content-Type: text/plain;charset=utf-8 -Content-Length: 609 -Cache-Control: must-revalidate - - -

- -

- - <literal>PUT /db/doc</literal> - - - - - -URL API PUT /db/docMethodPUT /db/docRequest - JSON of the new document, or updated version of the existed - document - Response - JSON of the document ID and revision - Admin Privileges RequirednoQuery ArgumentsArgumentbatchDescription - Allow document store request to be batched with others - OptionalyesTypestringSupported ValuesokEnableHTTP HeadersHeaderIf-MatchDescriptionCurrent revision of the document for validationOptionalyesReturn Codes201 - Document has been created successfully - 202 - Document accepted for writing (batch mode) - - - - The PUT method creates a new named document, or - creates a new revision of the existing document. Unlike the - POST - method, you must specify the document ID in the request URL. - - - - For example, to create the docment FishStew, - you would send the following request: - - -PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh bread", - "title" : "Fish Stew" -} - - - - The return type is JSON of the status, document ID,and revision - number: - - - -{ - "id" : "FishStew", - "ok" : true, - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} - - -

- - Updating an Existing Document - - - To update an existing document you must specify the current - revision number within the _rev parameter. - For example: - - - -PUT http://couchdb:5984/recipes/FishStew -Content-Type: application/json - -{ - "_rev" : "1-9c65296036141e575d32ba9c034dd3ee", - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -} - - - - Alternatively, you can supply the current revision number in the - If-Match HTTP header of the request. For - example: - - - -PUT http://couchdb:5984/recipes/FishStew -If-Match: 2-d953b18035b76f2a5b1d1d93f25d3aea -Content-Type: application/json - -{ - "servings" : 4, - "subtitle" : "Delicious with fresh salad", - "title" : "Fish Stew" -} - - - - The JSON returned will include the updated revision number: - - - -{ - "id" : "FishStew99", - "ok" : true, - "rev" : "2-d953b18035b76f2a5b1d1d93f25d3aea" -} - - - - For information on batched writes, which can provide improved - performance, see - . - - -

- -

- - <literal>DELETE /db/doc</literal> - - - - - -URL API DELETE /db/docMethodDELETE /db/docRequest - None - Response - JSON of the deleted revision - Admin Privileges RequirednoQuery ArgumentsArgumentrevDescription - Current revision of the document for validation - OptionalyesTypestringHTTP HeadersHeaderIf-MatchDescriptionCurrent revision of the document for validationOptionalyesReturn Codes409 - Revision is missing, invalid or not the latest - - - - Deletes the specified document from the database. You must supply - the current (latest) revision, either by using the - rev parameter to specify the revision: - - - -DELETE http://couchdb:5984/recipes/FishStew?rev=3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json - - - - Alternatively, you can use ETags with the - If-Match field: - - - -DELETE http://couchdb:5984/recipes/FishStew -If-Match: 3-a1a9b39ee3cc39181b796a69cb48521c -Content-Type: application/json - - - - The returned JSON contains the document ID, revision and status: - - - -{ - "id" : "FishStew", - "ok" : true, - "rev" : "4-2719fd41187c60762ff584761b714cfb" -} - - - - - Note that deletion of a record increments the revision number. - The use of a revision for deletion of the record allows - replication of the database to correctly track the deletion in - synchronized copies. - - - -

- -

- - <literal>COPY /db/doc</literal> - - - - - -URL API COPY /db/docMethodCOPY /db/docRequest - None - Response - JSON of the new document and revision - Admin Privileges RequirednoQuery ArgumentsArgumentrevDescription - Revision to copy from - OptionalyesTypestringHTTP HeadersHeaderDestinationDescriptionDestination document (and optional revision)OptionalnoReturn Codes201 - Document has been copied and created successfully - 409 - Conflict (target document already exists) - - - - The COPY command (which is non-standard HTTP) - copies an existing document to a new or existing document. - - - - The source document is specified on the request line, with the - Destination HTTP Header of the request - specifying the target document. - - -

- - Copying a Document - - - You can copy the latest version of a document to a new document - by specifying the current document and target document: - - - -COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew - - - - The above request copies the document - FishStew to the new document - IrishFishStew. The response is the ID and - revision of the new document. - - - -{ - "id" : "IrishFishStew", - "rev" : "1-9c65296036141e575d32ba9c034dd3ee" -} - - -

- -

- - Copying from a Specific Revision - - - To copy from a specific version, use the - rev argument to the query string: - - - -COPY http://couchdb:5984/recipes/FishStew?rev=5-acfd32d233f07cea4b4f37daaacc0082 -Content-Type: application/json -Destination: IrishFishStew - - - - The new document will be created using the information in the - specified revision of the source document. - - -

- -

- - Copying to an Existing Document - - - To copy to an existing document, you must specify the current - revision string for the target document, using the - rev parameter to the - Destination HTTP Header string. For example: - - - -COPY http://couchdb:5984/recipes/FishStew -Content-Type: application/json -Destination: IrishFishStew?rev=1-9c65296036141e575d32ba9c034dd3ee - - - - The return value will be the new revision of the copied - document: - - - -{ - "id" : "IrishFishStew", - "rev" : "2-55b6a1b251902a2c249b667dab1c6692" -} - - -

- -

- - <literal>GET /db/doc/attachment</literal> - - - - - -URL API GET /db/doc/attachmentMethodGET /db/doc/attachmentRequest - None - Response - Returns the document data - Admin Privileges Requiredno - - - Returns the file attachment attachment - associated with the document doc. The raw data - of the associated attachment is returned (just as if you were - accessing a static file. The returned HTTP - Content-type will be the same as the content - type set when the document attachment was submitted into the - database. - - -

- -

- - <literal>PUT /db/doc/attachment</literal> - - - - - -URL API PUT /db/doc/attachmentMethodPUT /db/doc/attachmentRequest - Raw document data - Response - JSON document status - Admin Privileges RequirednoQuery ArgumentsArgumentrevDescription - Current document revision - OptionalnoTypestringHTTP HeadersHeaderContent-LengthDescriptionLength (bytes) of the attachment being uploadedOptionalnoHeaderContent-TypeDescriptionMIME type for the uploaded attachmentOptionalnoHeaderIf-MatchDescriptionCurrent revision of the document for validationOptionalyesReturn Codes201 - Attachment has been accepted - - - - Upload the supplied content as an attachment to the specified - document (doc). The - attachment name provided must be a URL encoded - string. You must also supply either the rev - query argument or the If-Match HTTP header for - validation, and the HTTP headers (to set the attacment content - type). The content type is used when the attachment is requested - as the corresponding content-type in the returned document header. - - - - For example, you could upload a simple text document using the - following request: - - - -PUT http://couchdb:5984/recipes/FishStew/basic?rev=8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it - - - - - Or by using the If-Match HTTP header: - - - -PUT http://couchdb:5984/recipes/FishStew/basic -If-Match: 8-a94cb7e50ded1e06f943be5bfbddf8ca -Content-Length: 10 -Content-Type: text/plain - -Roast it - - - - - The returned JSON contains the new document information: - - - -{ - "id" : "FishStew", - "ok" : true, - "rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74" -} - - - - - Uploading an attachment updates the corresponding document - revision. Revisions are tracked for the parent document, not - individual attachments. - - - -

- - Updating an Existing Attachment - - - Uploading an attachment using an existing attachment name will - update the corresponding stored content of the database. Since - you must supply the revision information to add an attachment to - a document, this serves as validation to update the existing - attachment. - - -

- -

- - <literal>DELETE /db/doc/attachment</literal> - - - - - -URL API DELETE /db/doc/attachmentMethodDELETE /db/doc/attachmentRequest - None - Response - JSON status - Admin Privileges RequirednoQuery ArgumentsArgumentrevDescription - Revision of the document to be deleted - OptionalnoTypestringHTTP HeadersHeaderIf-MatchDescriptionCurrent revision of the document for validationOptionalyesReturn Codes200 - Attachment deleted successfully - 409 - Supplied revision is incorrect or missing - - - - Deletes the attachment attachment to the - specified doc. You must supply the - rev argument with the current revision to - delete the attachment. - - - - For example to delete the attachment basic from - the recipe FishStew: - - - -DELETE http://couchdb:5984/recipes/FishStew/basic?rev=9-247bb19a41bfd9bfdaf5ee6e2e05be74 -Content-Type: application/json - - - - - The returned JSON contains the updated revision information: - - - -{ - "id" : "FishStew", - "ok" : true, - "rev" : "10-561bf6b1e27615cee83d1f48fa65dd3e" -} - - -

- -