10.4.1. /db/doc¶
- HEAD /{db}/{docid}¶
Returns the HTTP Headers containing a minimal amount of information about the specified document. The method supports the same query arguments as the GET /{db}/{docid} method, but only the header information (including document size, and the revision as an ETag), is returned.
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 (see GET /{db}/{docid}), then the resulting HTTP Headers will correspond to what would be returned.
Parameters: - db – Database name
- docid – Document ID
Request Headers: - If-None-Match – Double quoted document’s revision token
Response Headers: - Content-Length – Document size
- ETag – Double quoted document’s revision token
Status Codes: - 200 OK – Document exists
- 304 Not Modified – Document wasn’t modified since specified revision
- 401 Unauthorized – Read privilege required
- 404 Not Found – Document not found
Request:
HEAD /db/SpaghettiWithMeatballs HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 660 Content-Type: application/json Date: Tue, 13 Aug 2013 21:35:37 GMT ETag: "12-151bb8678d45aaa949ec3698ef1c7e78" Server: CouchDB (Erlang/OTP)
- GET /{db}/{docid}¶
Returns document by the specified docid from the specified db. Unless you request a specific revision, the latest revision of the document will always be returned.
Parameters: - db – Database name
- docid – Document ID
Request Headers: - Accept –
- application/json
- multipart/related
- multipart/mixed
- text/plain
- If-None-Match – Double quoted document’s revision token
Query Parameters: - attachments (boolean) – Includes attachments bodies in response. Default is false
- att_encoding_info (boolean) – Includes encoding information in attachment stubs if the particular attachment is compressed. Default is false.
- atts_since (array) – Includes attachments only since specified revisions. Doesn’t includes attachments for specified revisions. Optional
- conflicts (boolean) – Includes information about conflicts in document. Default is false
- deleted_conflicts (boolean) – Includes information about deleted conflicted revisions. Default is false
- latest (boolean) – Forces retrieving latest “leaf” revision, no matter what rev was requested. Default is false
- local_seq (boolean) – Includes last update sequence for the document. Default is false
- meta (boolean) – Acts same as specifying all conflicts, deleted_conflicts and revs_info query parameters. Default is false
- open_revs (array) – Retrieves documents of specified leaf revisions. Additionally, it accepts value as all to return all leaf revisions. Optional
- rev (string) – Retrieves document of specified revision. Optional
- revs (boolean) – Includes list of all known document revisions. Default is false
- revs_info (boolean) – Includes detailed information for all known document revisions. Default is false
Response Headers: - Content-Type –
- application/json
- multipart/related
- multipart/mixed
- text/plain; charset=utf-8
- ETag – Double quoted document’s revision token. Not available when retrieving conflicts-related information
- Transfer-Encoding – chunked. Available if requested with query parameter open_revs
Response JSON Object: - _id (string) – Document ID
- _rev (string) – Revision MVCC token
- _deleted (boolean) – Deletion flag. Available if document was removed
- _attachments (object) – Attachment’s stubs. Available if document has any attachments
- _conflicts (array) – List of conflicted revisions. Available if requested with conflicts=true query parameter
- _deleted_conflicts (array) – List of deleted conflicted revisions. Available if requested with deleted_conflicts=true query parameter
- _local_seq (string) – Document’s update sequence in current database. Available if requested with local_seq=true query parameter
- _revs_info (array) – List of objects with information about local revisions and their status. Available if requested with open_revs query parameter
- _revisions (object) – List of local revision tokens without. Available if requested with revs=true query parameter
Status Codes: - 200 OK – Request completed successfully
- 304 Not Modified – Document wasn’t modified since specified revision
- 400 Bad Request – The format of the request or revision was invalid
- 401 Unauthorized – Read privilege required
- 404 Not Found – Document not found
Request:
GET /recipes/SpaghettiWithMeatballs HTTP/1.1 Accept: application/json Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 660 Content-Type: application/json Date: Tue, 13 Aug 2013 21:35:37 GMT ETag: "1-917fa2381192822767f010b95b45325b" Server: CouchDB (Erlang/OTP) { "_id": "SpaghettiWithMeatballs", "_rev": "1-917fa2381192822767f010b95b45325b", "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.", "ingredients": [ "spaghetti", "tomato sauce", "meatballs" ], "name": "Spaghetti with meatballs" }
- PUT /{db}/{docid}¶
The PUT method creates a new named document, or creates a new revision of the existing document. Unlike the POST /{db}, you must specify the document ID in the request URL.
When updating an existing document, the current document revision must be included in the document (i.e. the request body), as the rev query parameter, or in the If-Match request header.
Parameters: - db – Database name
- docid – Document ID
Request Headers: - Accept –
- application/json
- text/plain
- Content-Type –
- application/json
- multipart/related
- If-Match – Document’s revision. Alternative to rev query parameter or document key. Optional
- X-Couch-Full-Commit – Overrides server’s commit policy. Possible values are: false and true. Optional
Query Parameters: - rev (string) – Document’s revision if updating an existing document. Alternative to If-Match header or document key. Optional
- batch (string) – Stores document in batch mode. Possible values: ok. Optional
- new_edits (boolean) – Prevents insertion of a conflicting document. Possible values: true (default) and false. If false, a well-formed _rev must be included in the document. new_edits=false is used by the replicator to insert documents into the target database even if that leads to the creation of conflicts. Optional
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
- multipart/related
- ETag – Quoted document’s new revision
- Location – Document URI
Response JSON Object: - id (string) – Document ID
- ok (boolean) – Operation status
- rev (string) – Revision MVCC token
Status Codes: - 201 Created – Document created and stored on disk
- 202 Accepted – Document data accepted, but not yet stored on disk
- 400 Bad Request – Invalid request body or parameters
- 401 Unauthorized – Write privileges required
- 404 Not Found – Specified database or document ID doesn’t exists
- 409 Conflict – Document with the specified ID already exists or specified revision is not latest for target document
Request:
PUT /recipes/SpaghettiWithMeatballs HTTP/1.1 Accept: application/json Content-Length: 196 Content-Type: application/json Host: localhost:5984 { "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.", "ingredients": [ "spaghetti", "tomato sauce", "meatballs" ], "name": "Spaghetti with meatballs" }
Response:
HTTP/1.1 201 Created Cache-Control: must-revalidate Content-Length: 85 Content-Type: application/json Date: Wed, 14 Aug 2013 20:31:39 GMT ETag: "1-917fa2381192822767f010b95b45325b" Location: http://localhost:5984/recipes/SpaghettiWithMeatballs Server: CouchDB (Erlang/OTP) { "id": "SpaghettiWithMeatballs", "ok": true, "rev": "1-917fa2381192822767f010b95b45325b" }
- DELETE /{db}/{docid}¶
Marks the specified document as deleted by adding a field _deleted with the value true. Documents with this field will not be returned within requests anymore, but stay in the database. You must supply the current (latest) revision, either by using the rev parameter or by using the If-Match header to specify the revision.
Note
CouchDB doesn’t completely delete the specified document. Instead, it leaves a tombstone with very basic information about the document. The tombstone is required so that the delete action can be replicated across databases.
See also
Parameters: - db – Database name
- docid – Document ID
Request Headers: - Accept –
- application/json
- text/plain
- If-Match – Document’s revision. Alternative to rev query parameter
- X-Couch-Full-Commit – Overrides server’s commit policy. Possible values are: false and true. Optional
Query Parameters: - rev (string) – Actual document’s revision
- batch (string) – Stores document in batch mode Possible values: ok. Optional
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
- ETag – Double quoted document’s new revision
Response JSON Object: - id (string) – Document ID
- ok (boolean) – Operation status
- rev (string) – Revision MVCC token
Status Codes: - 200 OK – Document successfully removed
- 202 Accepted – Request was accepted, but changes are not yet stored on disk
- 400 Bad Request – Invalid request body or parameters
- 401 Unauthorized – Write privileges required
- 404 Not Found – Specified database or document ID doesn’t exists
- 409 Conflict – Specified revision is not the latest for target document
Request:
DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1 Accept: application/json Host: localhost:5984
Alternatively, instead of rev query parameter you may use If-Match header:
DELETE /recipes/FishStew HTTP/1.1 Accept: application/json If-Match: 1-9c65296036141e575d32ba9c034dd3ee Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 71 Content-Type: application/json Date: Wed, 14 Aug 2013 12:23:13 GMT ETag: "2-056f5f44046ecafc08a2bc2b9c229e20" Server: CouchDB (Erlang/OTP) { "id": "FishStew", "ok": true, "rev": "2-056f5f44046ecafc08a2bc2b9c229e20" }
- COPY /{db}/{docid}¶
The COPY (which is non-standard HTTP) copies an existing document to a new or existing document. Copying a document is only possible within the same database.
The source document is specified on the request line, with the Destination header of the request specifying the target document.
Parameters: - db – Database name
- docid – Document ID
Request Headers: - Accept –
- application/json
- text/plain
- Destination – Destination document. Must contain the target document ID, and optionally the target document revision, if copying to an existing document. See Copying to an Existing Document.
- If-Match – Source document’s revision. Alternative to rev query parameter
- X-Couch-Full-Commit – Overrides server’s commit policy. Possible values are: false and true. Optional
Query Parameters: - rev (string) – Revision to copy from. Optional
- batch (string) – Stores document in batch mode Possible values: ok. Optional
Response Headers: - Content-Type –
- application/json
- text/plain; charset=utf-8
- ETag – Double quoted document’s new revision
- Location – Document URI
Response JSON Object: - id (string) – Document document ID
- ok (boolean) – Operation status
- rev (string) – Revision MVCC token
Status Codes: - 201 Created – Document successfully created
- 202 Accepted – Request was accepted, but changes are not yet stored on disk
- 400 Bad Request – Invalid request body or parameters
- 401 Unauthorized – Read or write privileges required
- 404 Not Found – Specified database, document ID or revision doesn’t exists
- 409 Conflict – Document with the specified ID already exists or specified revision is not latest for target document
Request:
COPY /recipes/SpaghettiWithMeatballs HTTP/1.1 Accept: application/json Destination: SpaghettiWithMeatballs_Italian Host: localhost:5984
Response:
HTTP/1.1 201 Created Cache-Control: must-revalidate Content-Length: 93 Content-Type: application/json Date: Wed, 14 Aug 2013 14:21:00 GMT ETag: "1-e86fdf912560c2321a5fcefc6264e6d9" Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian Server: CouchDB (Erlang/OTP) { "id": "SpaghettiWithMeatballs_Italian", "ok": true, "rev": "1-e86fdf912560c2321a5fcefc6264e6d9" }
10.4.1.1. Attachments¶
If the document includes attachments, then the returned structure will contain a summary of the attachments associated 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.
The _attachments object keys are attachments names while values are information objects with next structure:
content_type (string): Attachment MIME type
data (string): Base64-encoded content. Available if attachment content is requested by using the following query parameters:
- attachments=true when querying a document
- attachments=true&include_docs=true when querying a changes feed or a view
- atts_since.
digest (string): Content hash digest. It starts with prefix which announce hash type (md5-) and continues with Base64-encoded hash digest
encoded_length (number): Compressed attachment size in bytes. Available if content_type is in list of compressible types when the attachment was added and the following query parameters are specified:
- att_encoding_info=true when querying a document
- att_encoding_info=true&include_docs=true when querying a changes feed or a view
encoding (string): Compression codec. Available if content_type is in list of compressible types when the attachment was added and the following query parameters are specified:
- att_encoding_info=true when querying a document
- att_encoding_info=true&include_docs=true when querying a changes feed or a view
length (number): Real attachment size in bytes. Not available if attachment content requested
revpos (number): Revision number when attachment was added
stub (boolean): Has true value if object contains stub info and no content. Otherwise omitted in response
10.4.1.1.1. Basic Attachments Info¶
Request:
GET /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 660
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
Server: CouchDB (Erlang/OTP)
{
"_attachments": {
"grandma_recipe.txt": {
"content_type": "text/plain",
"digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
"length": 1872,
"revpos": 4,
"stub": true
},
"my_recipe.txt": {
"content_type": "text/plain",
"digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
"length": 85,
"revpos": 5,
"stub": true
},
"photo.jpg": {
"content_type": "image/jpeg",
"digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
"length": 165504,
"revpos": 2,
"stub": true
}
},
"_id": "SpaghettiWithMeatballs",
"_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs"
}
10.4.1.1.2. Retrieving Attachments Content¶
It’s possible to retrieve document with all attached files content by using attachments=true query parameter:
Request:
GET /db/pixel?attachments=true HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 553
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:32:40 GMT
ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
Server: CouchDB (Erlang/OTP)
{
"_attachments": {
"pixel.gif": {
"content_type": "image/gif",
"data": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
"digest": "md5-2JdGiI2i2VELZKnwMers1Q==",
"revpos": 2
},
"pixel.png": {
"content_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAAXNSR0IArs4c6QAAAANQTFRFAAAAp3o92gAAAAF0Uk5TAEDm2GYAAAABYktHRACIBR1IAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3QgOCx8VHgmcNwAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=",
"digest": "md5-Dgf5zxgGuchWrve73evvGQ==",
"revpos": 3
}
},
"_id": "pixel",
"_rev": "4-f1bcae4bf7bbb92310079e632abfe3f4"
}
Or retrieve attached files content since specific revision using atts_since query parameter:
Request:
GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22] HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 760
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
Server: CouchDB (Erlang/OTP)
{
"_attachments": {
"grandma_recipe.txt": {
"content_type": "text/plain",
"digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
"length": 1872,
"revpos": 4,
"stub": true
},
"my_recipe.txt": {
"content_type": "text/plain",
"data": "MS4gQ29vayBzcGFnaGV0dGkKMi4gQ29vayBtZWV0YmFsbHMKMy4gTWl4IHRoZW0KNC4gQWRkIHRvbWF0byBzYXVjZQo1LiAuLi4KNi4gUFJPRklUIQ==",
"digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
"revpos": 5
},
"photo.jpg": {
"content_type": "image/jpeg",
"digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
"length": 165504,
"revpos": 2,
"stub": true
}
},
"_id": "SpaghettiWithMeatballs",
"_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs"
}
10.4.1.1.2.1. Efficient Multiple Attachments Retrieving¶
As noted above, retrieving document with attachments=true returns a large JSON object with all attachments included. When your document and files are smaller it’s ok, but if you have attached something bigger like media files (audio/video), parsing such response might be very expensive.
To solve this problem, CouchDB allows to get documents in multipart/related format:
Request:
GET /recipes/secret?attachments=true HTTP/1.1
Accept: multipart/related
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Content-Length: 538
Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
Date: Sat, 28 Sep 2013 08:08:22 GMT
ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
Server: CouchDB (Erlang OTP)
--e89b3e29388aef23453450d10e5aaed0
Content-Type: application/json
{"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
--e89b3e29388aef23453450d10e5aaed0
Content-Disposition: attachment; filename="recipe.txt"
Content-Type: text/plain
Content-Length: 86
1. Take R
2. Take E
3. Mix with L
4. Add some A
5. Serve with X
--e89b3e29388aef23453450d10e5aaed0--
In this response the document contains only attachments stub information and quite short while all attachments goes as separate entities which reduces memory footprint and processing overhead (you’d noticed, that attachment content goes as raw data, not in base64 encoding, right?).
10.4.1.1.3. Retrieving Attachments Encoding Info¶
By using att_encoding_info=true query parameter you may retrieve information about compressed attachments size and used codec.
Request:
GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 736
Content-Type: application/json
Date: Tue, 13 Aug 2013 21:35:37 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
Server: CouchDB (Erlang/OTP)
{
"_attachments": {
"grandma_recipe.txt": {
"content_type": "text/plain",
"digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
"encoded_length": 693,
"encoding": "gzip",
"length": 1872,
"revpos": 4,
"stub": true
},
"my_recipe.txt": {
"content_type": "text/plain",
"digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
"encoded_length": 100,
"encoding": "gzip",
"length": 85,
"revpos": 5,
"stub": true
},
"photo.jpg": {
"content_type": "image/jpeg",
"digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
"length": 165504,
"revpos": 2,
"stub": true
}
},
"_id": "SpaghettiWithMeatballs",
"_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs"
}
10.4.1.1.4. Creating Multiple Attachments¶
To create a document with multiple attachments with single request you need just inline base64 encoded attachments data into the document body:
{
"_id":"multiple_attachments",
"_attachments":
{
"foo.txt":
{
"content_type":"text\/plain",
"data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
},
"bar.txt":
{
"content_type":"text\/plain",
"data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
}
}
}
Alternatively, you can upload a document with attachments more efficiently in multipart/related format. This avoids having to Base64-encode the attachments, saving CPU and bandwidth. To do this, set the Content-Type header of the PUT /{db}/{docid} request to multipart/related.
The first MIME body is the document itself, which should have its own Content-Type of application/json". It also should include an _attachments metadata object in which each attachment object has a key follows with value true.
The subsequent MIME bodies are the attachments.
Request:
PUT /temp/somedoc HTTP/1.1
Accept: application/json
Content-Length: 372
Content-Type: multipart/related;boundary="abc123"
Host: localhost:5984
User-Agent: HTTPie/0.6.0
--abc123
Content-Type: application/json
{
"body": "This is a body.",
"_attachments": {
"foo.txt": {
"follows": true,
"content_type": "text/plain",
"length": 21
},
"bar.txt": {
"follows": true,
"content_type": "text/plain",
"length": 20
}
}
}
--abc123
this is 21 chars long
--abc123
this is 20 chars lon
--abc123--
Response:
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 72
Content-Type: application/json
Date: Sat, 28 Sep 2013 09:13:24 GMT
ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
Location: http://localhost:5984/temp/somedoc
Server: CouchDB (Erlang OTP)
{
"id": "somedoc",
"ok": true,
"rev": "1-5575e26acdeb1df561bb5b70b26ba151"
}
10.4.1.2. 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:
Request:
GET /recipes/SpaghettiWithMeatballs?revs=true HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 584
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:38:26 GMT
ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
"_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
"_revisions": {
"ids": [
"6f5ad8db0f34af24a6e0984cd1a6cfb9",
"77fba3a059497f51ec99b9b478b569d2",
"136813b440a00a24834f5cb1ddf5b1f1",
"fd96acb3256302bf0dd2f32713161f2a",
"874985bc28906155ba0e2e0538f67b05",
"0de77a37463bf391d14283e626831f2e",
"d795d1b924777732fdea76538c558b62",
"917fa2381192822767f010b95b45325b"
],
"start": 8
},
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs"
}
The returned JSON structure includes the original document, including a _revisions structure that includes the revision information in next form:
- ids (array): Array of valid revision IDs, in reverse order (latest first)
- start (number): Prefix number for the latest revision
10.4.1.3. 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:
Request:
GET /recipes/SpaghettiWithMeatballs?revs_info=true HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 802
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:40:55 GMT
Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
"_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
"_revs_info": [
{
"rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
"status": "available"
},
{
"rev": "7-77fba3a059497f51ec99b9b478b569d2",
"status": "deleted"
},
{
"rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
"status": "available"
},
{
"rev": "5-fd96acb3256302bf0dd2f32713161f2a",
"status": "missing"
},
{
"rev": "4-874985bc28906155ba0e2e0538f67b05",
"status": "missing"
},
{
"rev": "3-0de77a37463bf391d14283e626831f2e",
"status": "missing"
},
{
"rev": "2-d795d1b924777732fdea76538c558b62",
"status": "missing"
},
{
"rev": "1-917fa2381192822767f010b95b45325b",
"status": "missing"
}
],
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs"
}
The returned document contains _revs_info field with extended revision information, including the availability and status of each revision. This array field contains objects with following structure:
- rev (string): Full revision string
- status (string): Status of the revision.
Maybe one of:
- available: Revision is available for retrieving with rev query parameter
- missing: Revision is not available
- deleted: Revision belongs to deleted document
10.4.1.4. Obtaining a Specific Revision¶
To get a specific revision, use the rev argument to the request, and specify the full revision number. The specified revision of the document will be returned, including a _rev field specifying the revision that was requested.
Request:
GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1 HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 271
Content-Type: application/json
Date: Wed, 14 Aug 2013 11:40:55 GMT
Server: CouchDB (Erlang/OTP)
{
"_id": "SpaghettiWithMeatballs",
"_rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs"
}
10.4.1.4.1. Retrieving Deleted Documents¶
CouchDB doesn’t actually delete documents via DELETE /{db}/{docid}. Instead, it leaves tombstone with very basic information about the document. If you just GET /{db}/{docid} CouchDB returns 404 Not Found response:
Request:
GET /recipes/FishStew HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 404 Object Not Found
Cache-Control: must-revalidate
Content-Length: 41
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:23:27 GMT
Server: CouchDB (Erlang/OTP)
{
"error": "not_found",
"reason": "deleted"
}
However, you may retrieve document’s tombstone by using rev query parameter with GET /{db}/{docid} request:
Request:
GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20 HTTP/1.1
Accept: application/json
Host: localhost:5984
Response:
HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 79
Content-Type: application/json
Date: Wed, 14 Aug 2013 12:30:22 GMT
ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
Server: CouchDB (Erlang/OTP)
{
"_deleted": true,
"_id": "FishStew",
"_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
}
10.4.1.5. Updating an Existing Document¶
To update an existing document you must specify the current revision number within the _rev parameter.
Request:
PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
Content-Length: 258
Content-Type: application/json
Host: localhost:5984
{
"_rev": "1-917fa2381192822767f010b95b45325b",
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs",
"serving": "hot"
}
Alternatively, you can supply the current revision number in the If-Match HTTP header of the request:
PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
Content-Length: 258
Content-Type: application/json
If-Match: 1-917fa2381192822767f010b95b45325b
Host: localhost:5984
{
"description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
"ingredients": [
"spaghetti",
"tomato sauce",
"meatballs"
],
"name": "Spaghetti with meatballs",
"serving": "hot"
}
Response:
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 85
Content-Type: application/json
Date: Wed, 14 Aug 2013 20:33:56 GMT
ETag: "2-790895a73b63fb91dd863388398483dd"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs",
"ok": true,
"rev": "2-790895a73b63fb91dd863388398483dd"
}
10.4.1.6. Copying from a Specific Revision¶
To copy from a specific version, use the rev argument to the query string or If-Match:
Request:
COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
Accept: application/json
Destination: SpaghettiWithMeatballs_Original
If-Match: 1-917fa2381192822767f010b95b45325b
Host: localhost:5984
Response:
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 93
Content-Type: application/json
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "1-917fa2381192822767f010b95b45325b"
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Original
Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Original",
"ok": true,
"rev": "1-917fa2381192822767f010b95b45325b"
}
10.4.1.7. Copying to an Existing Document¶
To copy to an existing document, you must specify the current revision string for the target document by appending the rev parameter to the Destination header string.
Request:
COPY /recipes/SpaghettiWithMeatballs?rev=8-6f5ad8db0f34af24a6e0984cd1a6cfb9 HTTP/1.1
Accept: application/json
Destination: SpaghettiWithMeatballs_Original?rev=1-917fa2381192822767f010b95b45325b
Host: localhost:5984
Response:
HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 93
Content-Type: application/json
Date: Wed, 14 Aug 2013 14:21:00 GMT
ETag: "2-62e778c9ec09214dd685a981dcc24074""
Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Original
Server: CouchDB (Erlang/OTP)
{
"id": "SpaghettiWithMeatballs_Original",
"ok": true,
"rev": "2-62e778c9ec09214dd685a981dcc24074"
}