1.4.2. /{db}/{docid}/{attname}
- HEAD /{db}/{docid}/{attname}
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 ETag), is returned.- Parameters:
db – Database name
docid – Document ID
attname – Attachment name
- Request Headers:
If-Match – Document’s revision. Alternative to
rev
query parameterIf-None-Match – Attachment’s base64 encoded MD5 binary digest. Optional
- Query Parameters:
rev (string) – Document’s revision. Optional
- Response Headers:
Accept-Ranges – Range request aware. Used for attachments with application/octet-stream content type
Content-Encoding – Used compression codec. Available if attachment’s
content_type
is inlist of compressible types
Content-Length – Attachment size. If compression codec was used, this value is about compressed size, not actual
ETag – Double quoted base64 encoded MD5 binary digest
- Status Codes:
200 OK – Attachment exists
401 Unauthorized – Read privilege required
404 Not Found – Specified database, document or attachment was not found
Request:
HEAD /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1 Host: localhost:5984
Response:
HTTP/1.1 200 OK Accept-Ranges: none Cache-Control: must-revalidate Content-Encoding: gzip Content-Length: 100 Content-Type: text/plain Date: Thu, 15 Aug 2013 12:42:42 GMT ETag: "vVa/YgiE1+Gh0WfoFJAcSg==" 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 Content-Type 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 parameterIf-None-Match – Attachment’s base64 encoded MD5 binary digest. Optional
- Query Parameters:
rev (string) – Document’s revision. Optional
- Response Headers:
Accept-Ranges – Range request aware. Used for attachments with application/octet-stream
Content-Encoding – Used compression codec. Available if attachment’s
content_type
is inlist of compressible types
Content-Length – Attachment size. If compression codec is used, this value is about compressed size, not actual
ETag – Double quoted base64 encoded MD5 binary digest
- Response:
Stored content
- Status Codes:
200 OK – Attachment exists
401 Unauthorized – 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 If-Match 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:
Content-Type – Attachment MIME type. Default: application/octet-stream Optional
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:
201 Created – Attachment created and stored on disk
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, document or attachment was not found
409 Conflict – Document’s revision wasn’t specified or it’s not the latest
Request:
PUT /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1 Accept: application/json Content-Length: 86 Content-Type: text/plain Host: localhost:5984 If-Match: 1-917fa2381192822767f010b95b45325b 1. Cook spaghetti 2. Cook meatballs 3. Mix them 4. Add tomato sauce 5. ... 6. PROFIT!
Response:
HTTP/1.1 201 Created Cache-Control: must-revalidate Content-Length: 85 Content-Type: application/json Date: Thu, 15 Aug 2013 12:38:04 GMT ETag: "2-ce91aed0129be8f9b0f650a2edcfd0a4" Location: http://localhost:5984/recipes/SpaghettiWithMeatballs/recipe.txt Server: CouchDB (Erlang/OTP) { "id": "SpaghettiWithMeatballs", "ok": true, "rev": "2-ce91aed0129be8f9b0f650a2edcfd0a4" }
- DELETE /{db}/{docid}/{attname}
Deletes the attachment with filename
{attname}
of the specifieddoc
. You must supply therev
query parameter or If-Match 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
docid – Document ID
- Request Headers:
- Query Parameters:
rev (string) – Document revision. Required
batch (string) – Store changes in batch mode Possible values:
ok
. 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:
200 OK – Attachment 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, document or attachment was not found
409 Conflict – Document’s revision wasn’t specified or it’s not the latest
Request:
DELETE /recipes/SpaghettiWithMeatballs?rev=6-440b2dd39c20413045748b42c6aba6e2 HTTP/1.1 Accept: application/json Host: localhost:5984
Alternatively, instead of
rev
query parameter you may use If-Match header:DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1 Accept: application/json If-Match: 6-440b2dd39c20413045748b42c6aba6e2 Host: localhost:5984
Response:
HTTP/1.1 200 OK Cache-Control: must-revalidate Content-Length: 85 Content-Type: application/json Date: Wed, 14 Aug 2013 12:23:13 GMT ETag: "7-05185cf5fcdf4b6da360af939431d466" Server: CouchDB (Erlang/OTP) { "id": "SpaghettiWithMeatballs", "ok": true, "rev": "7-05185cf5fcdf4b6da360af939431d466" }
1.4.2.1. HTTP Range Requests
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).
shell> cat file.txt
My hovercraft is full of eels!
Now let’s store this text file as an attachment in CouchDB. First, we create a database:
shell> curl -X PUT http://adm:pass@127.0.0.1:5984/test
{"ok":true}
Then we create a new document and the file attachment in one go:
shell> curl -X PUT http://adm:pass@127.0.0.1:5984/test/doc/file.txt \
-H "Content-Type: application/octet-stream" -d@file.txt
{"ok":true,"id":"doc","rev":"1-287a28fa680ae0c7fb4729bf0c6e0cf2"}
Now we can request the whole file easily:
shell> curl -X GET http://adm:pass@127.0.0.1:5984/test/doc/file.txt
My hovercraft is full of eels!
But say we only want the first 13 bytes:
shell> curl -X GET http://adm:pass@127.0.0.1:5984/test/doc/file.txt \
-H "Range: bytes=0-12"
My hovercraft
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.4, 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.4 to take advantage of a better algorithm to find byte ranges.