[05/50] [abbrv] git commit: updated refs/heads/1781-reorganize-and-improve-docs to fa11c25

[kx...@apache.org]

Revert HTTP range requests as attachments API subsection.


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/5be91ece
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/5be91ece
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/5be91ece

Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: 5be91ece4af11f470203ab14fea8cecc867dca04
Parents: 485d001
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Jul 23 21:16:26 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Jul 24 10:48:37 2013 +0400

----------------------------------------------------------------------
 share/doc/src/api/documents.rst | 64 ++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/5be91ece/share/doc/src/api/documents.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/documents.rst b/share/doc/src/api/documents.rst
index ac2c763..a1ca0ab 100644
--- a/share/doc/src/api/documents.rst
+++ b/share/doc/src/api/documents.rst
@@ -831,6 +831,70 @@ if you were accessing a static file. The returned HTTP ``Content-type``
 will be the same as the content type set when the document attachment
 was submitted into the database.
 
+.. _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 ``application/octet-stream`` Content-Type
+instead of ``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`_.
+
+.. 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.
+
+.. _RFC 2616: http://tools.ietf.org/html/rfc2616#section-14.27
+
+
 .. _api/doc/attachment.put:
 
 ``PUT /db/doc/attachment``