1.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

    Response Headers

    Status Codes

Request:

  1. HEAD /db/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 660
  4. Content-Type: application/json
  5. Date: Tue, 13 Aug 2013 21:35:37 GMT
  6. ETag: "12-151bb8678d45aaa949ec3698ef1c7e78"
  7. 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

Request:

  1. GET /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 660
  4. Content-Type: application/json
  5. Date: Tue, 13 Aug 2013 21:35:37 GMT
  6. ETag: "1-917fa2381192822767f010b95b45325b"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_id": "SpaghettiWithMeatballs",
  11.     "_rev": "1-917fa2381192822767f010b95b45325b",
  12.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  13.     "ingredients": [
  14.         "spaghetti",
  15.         "tomato sauce",
  16.         "meatballs"
  17.     ],
  18.     "name": "Spaghetti with meatballs"
  19. }

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

    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, The ``false`` value is intended for use only by the replicator.

    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:

  1. PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Content-Length: 196
  4. Content-Type: application/json
  5. Host: localhost:5984
  7. {
  8.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  9.     "ingredients": [
  10.         "spaghetti",
  11.         "tomato sauce",
  12.         "meatballs"
  13.     ],
  14.     "name": "Spaghetti with meatballs"
  15. }

Response:

  1. HTTP/1.1 201 Created
  2. Cache-Control: must-revalidate
  3. Content-Length: 85
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 20:31:39 GMT
  6. ETag: "1-917fa2381192822767f010b95b45325b"
  7. Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
  8. Server: CouchDB (Erlang/OTP)
  10. {
  11.     "id": "SpaghettiWithMeatballs",
  12.     "ok": true,
  13.     "rev": "1-917fa2381192822767f010b95b45325b"
  14. }

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

Retrieving Deleted Documents

  • Parameters

    • db – Database name

    • docid – Document ID

    Request Headers

    • Accept –

      • application/json

      • text/plain

    • If-Match – Document’s revision. Alternative to rev query parameter

    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

Request:

  1. DELETE /recipes/FishStew?rev=1-9c65296036141e575d32ba9c034dd3ee HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Alternatively, instead of rev query parameter you may use If-Match header:

  1. DELETE /recipes/FishStew HTTP/1.1
  2. Accept: application/json
  3. If-Match: 1-9c65296036141e575d32ba9c034dd3ee
  4. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 71
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 12:23:13 GMT
  6. ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "id": "FishStew",
  11.     "ok": true,
  12.     "rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
  13. }

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

    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:

  1. COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Destination: SpaghettiWithMeatballs_Italian
  4. Host: localhost:5984

Response:

  1. HTTP/1.1 201 Created
  2. Cache-Control: must-revalidate
  3. Content-Length: 93
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 14:21:00 GMT
  6. ETag: "1-e86fdf912560c2321a5fcefc6264e6d9"
  7. Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Italian
  8. Server: CouchDB (Erlang/OTP)
  10. {
  11.     "id": "SpaghettiWithMeatballs_Italian",
  12.     "ok": true,
  13.     "rev": "1-e86fdf912560c2321a5fcefc6264e6d9"
  14. }

1.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

1.4.1.1.1. Basic Attachments Info

Request:

  1. GET /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 660
  4. Content-Type: application/json
  5. Date: Tue, 13 Aug 2013 21:35:37 GMT
  6. ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_attachments": {
  11.         "grandma_recipe.txt": {
  12.             "content_type": "text/plain",
  13.             "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
  14.             "length": 1872,
  15.             "revpos": 4,
  16.             "stub": true
  17.         },
  18.         "my_recipe.txt": {
  19.             "content_type": "text/plain",
  20.             "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
  21.             "length": 85,
  22.             "revpos": 5,
  23.             "stub": true
  24.         },
  25.         "photo.jpg": {
  26.             "content_type": "image/jpeg",
  27.             "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
  28.             "length": 165504,
  29.             "revpos": 2,
  30.             "stub": true
  31.         }
  32.     },
  33.     "_id": "SpaghettiWithMeatballs",
  34.     "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
  35.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  36.     "ingredients": [
  37.         "spaghetti",
  38.         "tomato sauce",
  39.         "meatballs"
  40.     ],
  41.     "name": "Spaghetti with meatballs"
  42. }

1.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:

  1. GET /db/pixel?attachments=true HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 553
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 11:32:40 GMT
  6. ETag: "4-f1bcae4bf7bbb92310079e632abfe3f4"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_attachments": {
  11.         "pixel.gif": {
  12.             "content_type": "image/gif",
  13.             "data": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
  14.             "digest": "md5-2JdGiI2i2VELZKnwMers1Q==",
  15.             "revpos": 2
  16.         },
  17.         "pixel.png": {
  18.             "content_type": "image/png",
  19.             "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQMAAAAl21bKAAAAAXNSR0IArs4c6QAAAANQTFRFAAAAp3o92gAAAAF0Uk5TAEDm2GYAAAABYktHRACIBR1IAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH3QgOCx8VHgmcNwAAAApJREFUCNdjYAAAAAIAAeIhvDMAAAAASUVORK5CYII=",
  20.             "digest": "md5-Dgf5zxgGuchWrve73evvGQ==",
  21.             "revpos": 3
  22.         }
  23.     },
  24.     "_id": "pixel",
  25.     "_rev": "4-f1bcae4bf7bbb92310079e632abfe3f4"
  26. }

Or retrieve attached files content since specific revision using atts_since query parameter:

Request:

  1. GET /recipes/SpaghettiWithMeatballs?atts_since=[%224-874985bc28906155ba0e2e0538f67b05%22]  HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 760
  4. Content-Type: application/json
  5. Date: Tue, 13 Aug 2013 21:35:37 GMT
  6. ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_attachments": {
  11.         "grandma_recipe.txt": {
  12.             "content_type": "text/plain",
  13.             "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
  14.             "length": 1872,
  15.             "revpos": 4,
  16.             "stub": true
  17.         },
  18.         "my_recipe.txt": {
  19.             "content_type": "text/plain",
  20.             "data": "MS4gQ29vayBzcGFnaGV0dGkKMi4gQ29vayBtZWV0YmFsbHMKMy4gTWl4IHRoZW0KNC4gQWRkIHRvbWF0byBzYXVjZQo1LiAuLi4KNi4gUFJPRklUIQ==",
  21.             "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
  22.             "revpos": 5
  23.         },
  24.         "photo.jpg": {
  25.             "content_type": "image/jpeg",
  26.             "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
  27.             "length": 165504,
  28.             "revpos": 2,
  29.             "stub": true
  30.         }
  31.     },
  32.     "_id": "SpaghettiWithMeatballs",
  33.     "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
  34.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  35.     "ingredients": [
  36.         "spaghetti",
  37.         "tomato sauce",
  38.         "meatballs"
  39.     ],
  40.     "name": "Spaghetti with meatballs"
  41. }

1.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:

  1. GET /recipes/secret?attachments=true HTTP/1.1
  2. Accept: multipart/related
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Content-Length: 538
  3. Content-Type: multipart/related; boundary="e89b3e29388aef23453450d10e5aaed0"
  4. Date: Sat, 28 Sep 2013 08:08:22 GMT
  5. ETag: "2-c1c6c44c4bc3c9344b037c8690468605"
  6. Server: CouchDB (Erlang OTP)
  8. --e89b3e29388aef23453450d10e5aaed0
  9. Content-Type: application/json
  11. {"_id":"secret","_rev":"2-c1c6c44c4bc3c9344b037c8690468605","_attachments":{"recipe.txt":{"content_type":"text/plain","revpos":2,"digest":"md5-HV9aXJdEnu0xnMQYTKgOFA==","length":86,"follows":true}}}
  12. --e89b3e29388aef23453450d10e5aaed0
  13. Content-Disposition: attachment; filename="recipe.txt"
  14. Content-Type: text/plain
  15. Content-Length: 86
  17. 1. Take R
  18. 2. Take E
  19. 3. Mix with L
  20. 4. Add some A
  21. 5. Serve with X
  23. --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?).

1.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:

  1. GET /recipes/SpaghettiWithMeatballs?att_encoding_info=true HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 736
  4. Content-Type: application/json
  5. Date: Tue, 13 Aug 2013 21:35:37 GMT
  6. ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_attachments": {
  11.         "grandma_recipe.txt": {
  12.             "content_type": "text/plain",
  13.             "digest": "md5-Ids41vtv725jyrN7iUvMcQ==",
  14.             "encoded_length": 693,
  15.             "encoding": "gzip",
  16.             "length": 1872,
  17.             "revpos": 4,
  18.             "stub": true
  19.         },
  20.         "my_recipe.txt": {
  21.             "content_type": "text/plain",
  22.             "digest": "md5-198BPPNiT5fqlLxoYYbjBA==",
  23.             "encoded_length": 100,
  24.             "encoding": "gzip",
  25.             "length": 85,
  26.             "revpos": 5,
  27.             "stub": true
  28.         },
  29.         "photo.jpg": {
  30.             "content_type": "image/jpeg",
  31.             "digest": "md5-7Pv4HW2822WY1r/3WDbPug==",
  32.             "length": 165504,
  33.             "revpos": 2,
  34.             "stub": true
  35.         }
  36.     },
  37.     "_id": "SpaghettiWithMeatballs",
  38.     "_rev": "5-fd96acb3256302bf0dd2f32713161f2a",
  39.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  40.     "ingredients": [
  41.         "spaghetti",
  42.         "tomato sauce",
  43.         "meatballs"
  44.     ],
  45.     "name": "Spaghetti with meatballs"
  46. }

1.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:

  1. {
  2.   "_id":"multiple_attachments",
  3.   "_attachments":
  4.   {
  5.     "foo.txt":
  6.     {
  7.       "content_type":"text\/plain",
  8.       "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
  9.     },
  11.    "bar.txt":
  12.     {
  13.       "content_type":"text\/plain",
  14.       "data": "VGhpcyBpcyBhIGJhc2U2NCBlbmNvZGVkIHRleHQ="
  15.     }
  16.   }
  17. }

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:

  1. PUT /temp/somedoc HTTP/1.1
  2. Accept: application/json
  3. Content-Length: 372
  4. Content-Type: multipart/related;boundary="abc123"
  5. Host: localhost:5984
  6. User-Agent: HTTPie/0.6.0
  8. --abc123
  9. Content-Type: application/json
  11. {
  12.     "body": "This is a body.",
  13.     "_attachments": {
  14.         "foo.txt": {
  15.             "follows": true,
  16.             "content_type": "text/plain",
  17.             "length": 21
  18.         },
  19.         "bar.txt": {
  20.             "follows": true,
  21.             "content_type": "text/plain",
  22.             "length": 20
  23.         }
  24.     }
  25. }
  27. --abc123
  29. this is 21 chars long
  30. --abc123
  32. this is 20 chars lon
  33. --abc123--

Response:

  1. HTTP/1.1 201 Created
  2. Cache-Control: must-revalidate
  3. Content-Length: 72
  4. Content-Type: application/json
  5. Date: Sat, 28 Sep 2013 09:13:24 GMT
  6. ETag: "1-5575e26acdeb1df561bb5b70b26ba151"
  7. Location: http://localhost:5984/temp/somedoc
  8. Server: CouchDB (Erlang OTP)
  10. {
  11.     "id": "somedoc",
  12.     "ok": true,
  13.     "rev": "1-5575e26acdeb1df561bb5b70b26ba151"
  14. }

1.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:

  1. GET /recipes/SpaghettiWithMeatballs?revs=true  HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 584
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 11:38:26 GMT
  6. ETag: "5-fd96acb3256302bf0dd2f32713161f2a"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_id": "SpaghettiWithMeatballs",
  11.     "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
  12.     "_revisions": {
  13.         "ids": [
  14.             "6f5ad8db0f34af24a6e0984cd1a6cfb9",
  15.             "77fba3a059497f51ec99b9b478b569d2",
  16.             "136813b440a00a24834f5cb1ddf5b1f1",
  17.             "fd96acb3256302bf0dd2f32713161f2a",
  18.             "874985bc28906155ba0e2e0538f67b05",
  19.             "0de77a37463bf391d14283e626831f2e",
  20.             "d795d1b924777732fdea76538c558b62",
  21.             "917fa2381192822767f010b95b45325b"
  22.         ],
  23.         "start": 8
  24.     },
  25.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  26.     "ingredients": [
  27.         "spaghetti",
  28.         "tomato sauce",
  29.         "meatballs"
  30.     ],
  31.     "name": "Spaghetti with meatballs"
  32. }

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

1.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:

  1. GET /recipes/SpaghettiWithMeatballs?revs_info=true  HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 802
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 11:40:55 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.     "_id": "SpaghettiWithMeatballs",
  10.     "_rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
  11.     "_revs_info": [
  12.         {
  13.             "rev": "8-6f5ad8db0f34af24a6e0984cd1a6cfb9",
  14.             "status": "available"
  15.         },
  16.         {
  17.             "rev": "7-77fba3a059497f51ec99b9b478b569d2",
  18.             "status": "deleted"
  19.         },
  20.         {
  21.             "rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
  22.             "status": "available"
  23.         },
  24.         {
  25.             "rev": "5-fd96acb3256302bf0dd2f32713161f2a",
  26.             "status": "missing"
  27.         },
  28.         {
  29.             "rev": "4-874985bc28906155ba0e2e0538f67b05",
  30.             "status": "missing"
  31.         },
  32.         {
  33.             "rev": "3-0de77a37463bf391d14283e626831f2e",
  34.             "status": "missing"
  35.         },
  36.         {
  37.             "rev": "2-d795d1b924777732fdea76538c558b62",
  38.             "status": "missing"
  39.         },
  40.         {
  41.             "rev": "1-917fa2381192822767f010b95b45325b",
  42.             "status": "missing"
  43.         }
  44.     ],
  45.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  46.     "ingredients": [
  47.         "spaghetti",
  48.         "tomato sauce",
  49.         "meatballs"
  50.     ],
  51.     "name": "Spaghetti with meatballs"
  52. }

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

1.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:

  1. GET /recipes/SpaghettiWithMeatballs?rev=6-136813b440a00a24834f5cb1ddf5b1f1  HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 271
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 11:40:55 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.     "_id": "SpaghettiWithMeatballs",
  10.     "_rev": "6-136813b440a00a24834f5cb1ddf5b1f1",
  11.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  12.     "ingredients": [
  13.         "spaghetti",
  14.         "tomato sauce",
  15.         "meatballs"
  16.     ],
  17.     "name": "Spaghetti with meatballs"
  18. }

1.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:

  1. GET /recipes/FishStew  HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 404 Object Not Found
  2. Cache-Control: must-revalidate
  3. Content-Length: 41
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 12:23:27 GMT
  6. Server: CouchDB (Erlang/OTP)
  8. {
  9.     "error": "not_found",
  10.     "reason": "deleted"
  11. }

However, you may retrieve document’s tombstone by using rev query parameter with GET /{db}/{docid} request:

Request:

  1. GET /recipes/FishStew?rev=2-056f5f44046ecafc08a2bc2b9c229e20  HTTP/1.1
  2. Accept: application/json
  3. Host: localhost:5984

Response:

  1. HTTP/1.1 200 OK
  2. Cache-Control: must-revalidate
  3. Content-Length: 79
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 12:30:22 GMT
  6. ETag: "2-056f5f44046ecafc08a2bc2b9c229e20"
  7. Server: CouchDB (Erlang/OTP)
  9. {
  10.     "_deleted": true,
  11.     "_id": "FishStew",
  12.     "_rev": "2-056f5f44046ecafc08a2bc2b9c229e20"
  13. }

1.4.1.5. Updating an Existing Document

To update an existing document you must specify the current revision number within the _rev parameter.

Request:

  1. PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Content-Length: 258
  4. Content-Type: application/json
  5. Host: localhost:5984
  7. {
  8.     "_rev": "1-917fa2381192822767f010b95b45325b",
  9.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  10.     "ingredients": [
  11.         "spaghetti",
  12.         "tomato sauce",
  13.         "meatballs"
  14.     ],
  15.     "name": "Spaghetti with meatballs",
  16.     "serving": "hot"
  17. }

Alternatively, you can supply the current revision number in the If-Match HTTP header of the request:

  1. PUT /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Content-Length: 258
  4. Content-Type: application/json
  5. If-Match: 1-917fa2381192822767f010b95b45325b
  6. Host: localhost:5984
  8. {
  9.     "description": "An Italian-American dish that usually consists of spaghetti, tomato sauce and meatballs.",
  10.     "ingredients": [
  11.         "spaghetti",
  12.         "tomato sauce",
  13.         "meatballs"
  14.     ],
  15.     "name": "Spaghetti with meatballs",
  16.     "serving": "hot"
  17. }

Response:

  1. HTTP/1.1 201 Created
  2. Cache-Control: must-revalidate
  3. Content-Length: 85
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 20:33:56 GMT
  6. ETag: "2-790895a73b63fb91dd863388398483dd"
  7. Location: http://localhost:5984/recipes/SpaghettiWithMeatballs
  8. Server: CouchDB (Erlang/OTP)
  10. {
  11.     "id": "SpaghettiWithMeatballs",
  12.     "ok": true,
  13.     "rev": "2-790895a73b63fb91dd863388398483dd"
  14. }

1.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:

  1. COPY /recipes/SpaghettiWithMeatballs HTTP/1.1
  2. Accept: application/json
  3. Destination: SpaghettiWithMeatballs_Original
  4. If-Match: 1-917fa2381192822767f010b95b45325b
  5. Host: localhost:5984

Response:

  1. HTTP/1.1 201 Created
  2. Cache-Control: must-revalidate
  3. Content-Length: 93
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 14:21:00 GMT
  6. ETag: "1-917fa2381192822767f010b95b45325b"
  7. Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Original
  8. Server: CouchDB (Erlang/OTP)
  10. {
  11.     "id": "SpaghettiWithMeatballs_Original",
  12.     "ok": true,
  13.     "rev": "1-917fa2381192822767f010b95b45325b"
  14. }

1.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:

  1. COPY /recipes/SpaghettiWithMeatballs?rev=8-6f5ad8db0f34af24a6e0984cd1a6cfb9 HTTP/1.1
  2. Accept: application/json
  3. Destination: SpaghettiWithMeatballs_Original?rev=1-917fa2381192822767f010b95b45325b
  4. Host: localhost:5984

Response:

  1. HTTP/1.1 201 Created
  2. Cache-Control: must-revalidate
  3. Content-Length: 93
  4. Content-Type: application/json
  5. Date: Wed, 14 Aug 2013 14:21:00 GMT
  6. ETag: "2-62e778c9ec09214dd685a981dcc24074""
  7. Location: http://localhost:5984/recipes/SpaghettiWithMeatballs_Original
  8. Server: CouchDB (Erlang/OTP)
  10. {
  11.     "id": "SpaghettiWithMeatballs_Original",
  12.     "ok": true,
  13.     "rev": "2-62e778c9ec09214dd685a981dcc24074"
  14. }