1.4.2. /db/doc/attachment

    Returns the HTTP headers containing a minimal amount of information about the specified attachment. The method supports the same query arguments as the GET /{db}/{docid}/{attname} method, but only the header information (including attachment size, encoding and the MD5 hash as an ), is returned.

    • Parameters

      • db – Database name

      • docid – Document ID

      • attname – Attachment name

      Request Headers

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

      • – Attachment’s base64 encoded MD5 binary digest. Optional

      Query Parameters

      • rev (string) – Document’s revision. Optional

      Response Headers

      • Accept-Ranges – . Used for attachments with application/octet-stream content type

      • Content-Encoding – Used compression codec. Available if attachment’s content_type is in

      • Content-Length – Attachment size. If compression codec was used, this value is about compressed size, not actual

      • – Double quoted base64 encoded MD5 binary digest

      Status Codes

      • 200 OK – Attachment exists

      • – Read privilege required

      • 404 Not Found – Specified database, document or attachment was not found

    Request:

    Response:

    1. HTTP/1.1 200 OK
    2. Accept-Ranges: none
    3. Cache-Control: must-revalidate
    4. Content-Encoding: gzip
    5. Content-Length: 100
    6. Content-Type: text/plain
    7. Date: Thu, 15 Aug 2013 12:42:42 GMT
    8. ETag: "vVa/YgiE1+Gh0WfoFJAcSg=="
    9. Server: CouchDB (Erlang/OTP)

    GET /{db}/{docid}/{attname}

    Returns the file attachment associated with the document. The raw data of the associated attachment is returned (just as if you were accessing a static file. The returned will be the same as the content type set when the document attachment was submitted into the database.

    • Parameters

      • db – Database name

      • docid – Document ID

      • attname – Attachment name

      Request Headers

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

      • – Attachment’s base64 encoded MD5 binary digest. Optional

      Query Parameters

      • rev (string) – Document’s revision. Optional

      Response Headers

      • Accept-Ranges – . Used for attachments with application/octet-stream

      • Content-Encoding – Used compression codec. Available if attachment’s content_type is in

      • Content-Length – Attachment size. If compression codec is used, this value is about compressed size, not actual

      • – Double quoted base64 encoded MD5 binary digest

      Response

      Status Codes

      • 200 OK – Attachment exists

      • – Read privilege required

      • 404 Not Found – Specified database, document or attachment was not found

    PUT /{db}/{docid}/{attname}

    Uploads the supplied content as an attachment to the specified document. The attachment name provided must be a URL encoded string. You must supply the Content-Type header, and for an existing document you must also supply either the rev query argument or the HTTP header. If the revision is omitted, a new, otherwise empty document will be created with the provided attachment, or a conflict will occur.

    If case when uploading an attachment using an existing attachment name, CouchDB will update the corresponding stored content of the database. Since you must supply the revision information to add an attachment to the document, this serves as validation to update the existing attachment.

    Note

    Uploading an attachment updates the corresponding document revision. Revisions are tracked for the parent document, not individual attachments.

    • Parameters

      • db – Database name

      • docid – Document ID

      • attname – Attachment name

      Request Headers

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

      Query Parameters

      • rev (string) – Document revision. Optional

      Response JSON Object

      • id (string) – Document ID

      • ok (boolean) – Operation status

      • rev (string) – Revision MVCC token

      Status Codes

      • – Attachment created and stored on disk

      • 202 Accepted – Request was accepted, but changes are not yet stored on disk

      • – Invalid request body or parameters

      • 401 Unauthorized – Write privileges required

      • – Specified database, document or attachment was not found

      • 409 Conflict – Document’s revision wasn’t specified or it’s not the latest

    Request:

    1. PUT /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
    2. Accept: application/json
    3. Content-Length: 86
    4. Content-Type: text/plain
    5. Host: localhost:5984
    8. 1. Cook spaghetti
    9. 2. Cook meatballs
    10. 3. Mix them
    11. 4. Add tomato sauce
    12. 5. ...
    13. 6. PROFIT!

    Response:

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

    DELETE /{db}/{docid}/{attname}

    Deletes the attachment with filename {attname} of the specified doc. You must supply the rev query parameter or with the current revision to delete the attachment.

    Note

    Deleting an attachment updates the corresponding document revision. Revisions are tracked for the parent document, not individual attachments.

    • Parameters

      • db – Database name

      Request Headers

      • Accept –

        • text/plain

      • – Document revision. Alternative to rev query parameter

      Query Parameters

      • rev (string) – Document revision. Required

      • batch (string) – Store changes in batch mode Possible values: . Optional

      Response Headers

      • –

        • 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

      • – Attachment successfully removed

      • 202 Accepted – Request was accepted, but changes are not yet stored on disk

      • – Invalid request body or parameters

      • 401 Unauthorized – Write privileges required

      • – Specified database, document or attachment was not found

      • 409 Conflict – Document’s revision wasn’t specified or it’s not the latest

    Request:

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

    1. DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1
    2. Accept: application/json
    3. If-Match: 6-440b2dd39c20413045748b42c6aba6e2
    4. Host: localhost:5984

    Response:

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

    HTTP allows you to specify byte ranges for requests. This allows the implementation of resumable downloads and skippable audio and video streams alike. This is available for all attachments inside CouchDB.

    This is just a real quick run through how this looks under the hood. Usually, you will have larger binary files to serve from CouchDB, like MP3s and videos, but to make things a little more obvious, I use a text file here (Note that I use the application/octet-stream :header`Content-Type` instead of text/plain).

    1. shell> cat file.txt
    2. My hovercraft is full of eels!

    Now let’s store this text file as an attachment in CouchDB. First, we create a database:

    Then we create a new document and the file attachment in one go:

    1. shell> curl -X PUT http://127.0.0.1:5984/test/doc/file.txt \
    2.             -H "Content-Type: application/octet-stream" -d@file.txt
    3. {"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}

    Now we can request the whole file easily:

    1. shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt
    2. My hovercraft is full of eels!

    But say we only want the first 13 bytes:

    1. shell> curl -X GET http://127.0.0.1:5984/test/doc/file.txt \

    HTTP supports many ways to specify single and even multiple byte ranges. Read all about it in RFC 2616#section-14.27.

    Note

    Databases that have been created with CouchDB 1.0.2 or earlier will support range requests in 3.2, but they are using a less-optimal algorithm. If you plan to make heavy use of this feature, make sure to compact your database with CouchDB 3.2 to take advantage of a better algorithm to find byte ranges.