.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

.. _api/doc/attachment:

======================
``/db/doc/attachment``
======================

.. http:head:: /{db}/{docid}/{attname}
    :synopsis: Returns bare information in the HTTP Headers for the 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
    :header:`ETag`), is returned.

    :param db: Database name
    :param docid: Document ID
    :param attname: Attachment name

    :<header If-Match: Document's revision. Alternative to ``rev`` query
      parameter
    :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
      *Optional*

    :query string rev: Document's revision. *Optional*

    :>header Accept-Ranges: :ref:`Range request aware
      <api/doc/attachment/range>`. Used for attachments with
      :mimetype:`application/octet-stream` content type
    :>header Content-Encoding: Used compression codec. Available if
      attachment's ``content_type`` is in :config:option:`list of compressible
      types <attachments/compressible_types>`
    :>header Content-Length: Attachment size. If compression codec was used,
      this value is about compressed size, not actual
    :>header ETag: Double quoted base64 encoded MD5 binary digest

    :code 200: Attachment exists
    :code 401: Read privilege required
    :code 404: Specified database, document or attachment was not found

    **Request**:

    .. code-block:: http

        HEAD /recipes/SpaghettiWithMeatballs/recipe.txt HTTP/1.1
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        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)

.. http:get:: /{db}/{docid}/{attname}
    :synopsis: Gets the attachment of a document

    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 :header:`Content-Type` will be the same as the
    content type set when the document attachment was submitted into the
    database.

    :param db: Database name
    :param docid: Document ID
    :param attname: Attachment name

    :<header If-Match: Document's revision. Alternative to ``rev`` query
      parameter
    :<header If-None-Match: Attachment's base64 encoded MD5 binary digest.
      *Optional*

    :query string rev: Document's revision. *Optional*

    :>header Accept-Ranges: :ref:`Range request aware
      <api/doc/attachment/range>`. Used for attachments with
      :mimetype:`application/octet-stream`
    :>header Content-Encoding: Used compression codec. Available if
      attachment's ``content_type`` is in :config:option:`list of compressible
      types <attachments/compressible_types>`
    :>header Content-Length: Attachment size. If compression codec is used,
      this value is about compressed size, not actual
    :>header ETag: Double quoted base64 encoded MD5 binary digest

    :response: Stored content

    :code 200: Attachment exists
    :code 401: Read privilege required
    :code 404: Specified database, document or attachment was not found

.. http:put:: /{db}/{docid}/{attname}
    :synopsis: Adds an attachment of a document

    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 :header:`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.

    :param db: Database name
    :param docid: Document ID
    :param attname: Attachment name

    :<header Content-Type: Attachment MIME type. Default: :mimetype:`application/octet-stream` *Optional*
    :<header If-Match: Document revision. Alternative to ``rev`` query parameter

    :query string rev: Document revision. *Optional*

    :>json string id: Document ID
    :>json boolean ok: Operation status
    :>json string rev: Revision MVCC token

    :code 201: Attachment created and stored on disk
    :code 202: Request was accepted, but changes are not yet stored on disk
    :code 400: Invalid request body or parameters
    :code 401: Write privileges required
    :code 404: Specified database, document or attachment was not found
    :code 409: Document's revision wasn't specified or it's not the latest

    **Request**:

    .. code-block:: http

        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**:

    .. code-block:: http

        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"
        }

.. http:delete:: /{db}/{docid}/{attname}
    :synopsis: Deletes an attachment of a document

    Deletes the attachment with filename ``{attname}`` of the specified ``doc``.
    You must supply the ``rev`` query parameter or :header:`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.

    :param db: Database name
    :param docid: Document ID
    :<header Accept: - :mimetype:`application/json`
                     - :mimetype:`text/plain`
    :<header If-Match: Document revision. Alternative to ``rev`` query parameter

    :query string rev: Document revision. *Required*
    :query string batch: Store changes in :ref:`batch mode
      <api/doc/batch-writes>` Possible values: ``ok``. *Optional*
    :>header Content-Type: - :mimetype:`application/json`
                           - :mimetype:`text/plain; charset=utf-8`
    :>header ETag: Double quoted document's new revision
    :>json string id: Document ID
    :>json boolean ok: Operation status
    :>json string rev: Revision MVCC token
    :code 200: Attachment successfully removed
    :code 202: Request was accepted, but changes are not yet stored on disk
    :code 400: Invalid request body or parameters
    :code 401: Write privileges required
    :code 404: Specified database, document or attachment was not found
    :code 409: Document's revision wasn't specified or it's not the latest

    **Request**:

    .. code-block:: http

        DELETE /recipes/SpaghettiWithMeatballs?rev=6-440b2dd39c20413045748b42c6aba6e2 HTTP/1.1
        Accept: application/json
        Host: localhost:5984

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

    .. code-block:: http

        DELETE /recipes/SpaghettiWithMeatballs HTTP/1.1
        Accept: application/json
        If-Match: 6-440b2dd39c20413045748b42c6aba6e2
        Host: localhost:5984

    **Response**:

    .. code-block:: http

        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"
        }

.. _api/doc/attachment/range:

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 :mimetype:`application/octet-stream` :header`Content-Type` instead of
:mimetype:`text/plain`).

.. code-block:: bash

    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:

.. code-block:: bash

    shell> curl -X PUT http://127.0.0.1:5984/test
    {"ok":true}

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

.. code-block:: bash

    shell> curl -X PUT http://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:

.. code-block:: bash

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

But say we only want the first 13 bytes:

.. code-block:: bash

    shell> curl -X GET http://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 |version|, 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 |version| to take advantage of a better algorithm to
    find byte ranges.