You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/08/21 18:37:48 UTC
[21/50] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to 360107b
Update Changes API. Provide reference for Last-Event-ID header.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/e168cc10
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/e168cc10
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/e168cc10
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: e168cc102ef615e291dc9a9b6e4fc5ed53f06a29
Parents: 2bc359c
Author: Alexander Shorin <kx...@apache.org>
Authored: Mon Aug 12 05:24:49 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Aug 21 20:29:39 2013 +0400
----------------------------------------------------------------------
share/doc/ext/httpdomain.py | 8 +
share/doc/src/api/database/changes.rst | 234 ++++++++++++++++------------
2 files changed, 140 insertions(+), 102 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/e168cc10/share/doc/ext/httpdomain.py
----------------------------------------------------------------------
diff --git a/share/doc/ext/httpdomain.py b/share/doc/ext/httpdomain.py
index 9ea0a80..3a16b42 100644
--- a/share/doc/ext/httpdomain.py
+++ b/share/doc/ext/httpdomain.py
@@ -62,6 +62,13 @@ class IETFRef(DocRef):
super(IETFRef, self).__init__(url, 'section-', section)
+class EventSourceRef(DocRef):
+
+ def __init__(self, section):
+ url = 'http://www.w3.org/TR/eventsource/'
+ super(EventSourceRef, self).__init__(url, section, '')
+
+
#: Mapping from lowercase HTTP method name to :class:`DocRef` object which
#: maintains the URL which points to the section of the RFC which defines that
#: HTTP method.
@@ -110,6 +117,7 @@ HEADER_REFS = {
'If-None-Match': RFC2616Ref(14.26),
'If-Range': RFC2616Ref(14.27),
'If-Unmodified-Since': RFC2616Ref(14.28),
+ 'Last-Event-ID': EventSourceRef('last-event-id'),
'Last-Modified': RFC2616Ref(14.29),
'Location': RFC2616Ref(14.30),
'Max-Forwards': RFC2616Ref(14.31),
http://git-wip-us.apache.org/repos/asf/couchdb/blob/e168cc10/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index acdc238..52a38a7 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -12,91 +12,136 @@
.. _api/db/changes:
-.. _api/db/changes.get:
-
-====================
-``GET /db/_changes``
-====================
-
-* **Method**: ``GET /db/_changes``
-* **Request**: None
-* **Response**: JSON success statement
-* **Admin Privileges Required**: no
-
-A list of changes made to documents in the database, in the order they were
-made, can be obtained from the database's ``_changes`` resource.
-This can be used to monitor for update and modifications to the database for
-post processing or synchronization. You can query the ``_changes`` resource by
-issuing a ``GET`` request with the following (optional) parameters:
-
-+--------------+----------------------------------------------+---------------+--------------+
-| Parameter | Value | Default Value | Notes |
-+==============+==============================================+===============+==============+
-| since | seqnum / now | 0 | \(1) |
-+--------------+----------------------------------------------+---------------+--------------+
-| limit | maxsequences | none | \(2) |
-+--------------+----------------------------------------------+---------------+--------------+
-| descending | boolean | false | \(3) |
-+--------------+----------------------------------------------+---------------+--------------+
-| feed | normal / longpoll / continuous / eventsource | normal | \(4) |
-+--------------+----------------------------------------------+---------------+--------------+
-| heartbeat | milliseconds | 60000 | \(5) |
-+--------------+----------------------------------------------+---------------+--------------+
-| timeout | milliseconds | 60000 | \(6) |
-+--------------+----------------------------------------------+---------------+--------------+
-| filter | designdoc/filtername / _view | none | \(7) |
-+--------------+----------------------------------------------+---------------+--------------+
-| include_docs | boolean | false | \(8) |
-+--------------+----------------------------------------------+---------------+--------------+
-| style | all_docs / main_only | main_only | \(9) |
-+--------------+----------------------------------------------+---------------+--------------+
-| view | designdoc/filtername | none | \(10) |
-+--------------+----------------------------------------------+---------------+--------------+
-
-Notes:
-
-(1) Start the results from the change immediately after the given sequence
- number.
-
-(2) Limit number of result rows to the specified value (note that using 0 here
- has the same effect as 1).
-
-(3) Return the change results in descending sequence order (most recent change
- first)
-
-(4) Select the type of feed.
-
-(5) Period in milliseconds after which an empty line is sent in the results.
- Only applicable for `longpoll` or `continuous` feeds. Overrides any timeout
- to keep the feed alive indefinitely.
-
-(6) Maximum period in milliseconds to wait for a change before the response is
- sent, even if there are no results. Only applicable for `longpoll` or
- `continuous` feeds. Note that 60000 is also the default maximum timeout to
- prevent undetected dead connections.
-
- You can change the default maximum timeout in your ini-configuration:
-
- .. code-block:: ini
-
- [httpd]
- changes_timeout=#millisecs
-
-(7) Reference to a :ref:`filter function <filterfun>` from a design document
- that will filter whole stream emitting only filtered events.
- See the `section in the book`_ for more information.
-
-(8) Include the associated document with each result. If there are conflicts,
- only the winning revision is returned.
-
-(9) Specifies how many revisions are returned in the changes array.
- The default, `main_only`, will only return the current "winning" revision;
- `all_docs` will return all leaf revisions (including conflicts and deleted
- former conflicts.)
-
-(10) Allows to use view functions as filters. It requires to set ``filter``
- special value `_view` to enable this feature. Documents counted as "passed"
- for view filter in case if map function emits at least one record for them.
+
+================
+``/db/_changes``
+================
+
+.. http:get:: /{db}/_changes
+.. http:head:: /{db}/_changes
+.. http:post:: /{db}/_changes
+
+ A list of changes made to documents in the database, in the order they were
+ made, can be obtained from the database's ``_changes`` resource.
+ This can be used to monitor for update and modifications to the database for
+ post processing or synchronization.
+
+ :param db: Database name
+ :<header Accept: - :mimetype:`application/json`
+ - :mimetype:`text/event-stream`
+ - :mimetype:`text/plain`
+ :<header Last-Event-ID: ID of the last events received by the server on a
+ previous connection. Overrides `since` query parameter.
+ :query boolean conflicts: Includes `conflicts` information in response.
+ Ignored if `include_docs` isn't ``true``. Default is ``false``.
+ :query boolean descending: Return the change results in descending sequence
+ order (most recent change first). Default is ``false``.
+ :query string feed: see :ref:`changes`. Default is ``normal``.
+ :query string filter: Reference to a :ref:`filter function <filterfun>`
+ from a design document that will filter whole stream emitting only filtered
+ events. See the `section in the book`_ for more information.
+ :query number heartbeat: Period in *milliseconds* after which an empty line is
+ sent in the results. Only applicable for :ref:`longpoll <changes/longpoll>`
+ or :ref:`continuous <changes/continuous>` feeds. Overrides any timeout to
+ keep the feed alive indefinitely. Default is ``60000``. May be ``true`` to
+ use default value.
+ :query boolean include_docs: Include the associated document with each result.
+ If there are conflicts, only the winning revision is returned.
+ Default is ``false``.
+ :query number last-event-id: Alias of `Last-Event-ID` header.
+ :query number limit: Limit number of result rows to the specified value
+ (note that using ``0`` here has the same effect as ``1``).
+ :query since: Start the results from the change immediately after the given
+ sequence number. Can be integer number or ``now`` value. Default is ``0``.
+ :query string style: Specifies how many revisions are returned in the changes
+ array. The default, ``main_only``, will only return the current "winning"
+ revision; ``all_docs`` will return all leaf revisions (including conflicts
+ and deleted former conflicts).
+ :query number timeout: Maximum period in *milliseconds* to wait for a change
+ before the response is sent, even if there are no results. Only applicable
+ for :ref:`longpoll <changes/longpoll>` or :ref:`continuous
+ <changes/continuous>` feeds. Default value is specified by
+ :ref:`changes_timeout <config/httpd/changes_timeout>` configuration option.
+ Note that ``60000`` value is also the default maximum timeout to prevent
+ undetected dead connections.
+ :query string view: Allows to use view functions as filters. It requires to
+ set ``filter`` special value ``_view`` to enable this feature.
+ Documents counted as "passed" for view filter in case if map function emits
+ at least one record for them.
+ :>header Cache-Control: ``no-cache`` if changes feed is
+ :ref:`eventsource <changes/eventsource>`
+ :>header Content-Type: - :mimetype:`application/json`
+ - :mimetype:`text/event-stream`
+ - :mimetype:`text/plain; charset=utf-8`
+ :>header ETag: Response hash is changes feed is `normal`
+ :>header Transfer-Encoding: ``chunked``
+ :>json number last_seq: Last change sequence number
+ :>json array results: Changes made to a database
+ :code 200: Request completed successfully
+
+ The ``result`` field of database changes
+
+ :json array changes: List of document`s leafs with single field ``rev``
+ :json string id: Document ID
+ :json number seq: Update sequence number
+
+ **Request**:
+
+ .. code-block:: http
+
+ GET /db/_changes?style=all_docs HTTP/1.1
+ Accept: application/json
+ Host: localhost:5984
+
+ **Response**:
+
+ .. code-block:: http
+
+ HTTP/1.1 200 OK
+ Cache-Control: must-revalidate
+ Content-Type: application/json
+ Date: Mon, 12 Aug 2013 00:54:58 GMT
+ ETag: "6ASLEKEMSRABT0O5XY9UPO9Z"
+ Server: CouchDB/1.4.0 (Erlang OTP/R16B)
+ Transfer-Encoding: chunked
+
+ {
+ "last_seq": 11,
+ "results": [
+ {
+ "changes": [
+ {
+ "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
+ }
+ ],
+ "id": "6478c2ae800dfc387396d14e1fc39626",
+ "seq": 6
+ },
+ {
+ "changes": [
+ {
+ "rev": "3-7379b9e515b161226c6559d90c4dc49f"
+ }
+ ],
+ "deleted": true,
+ "id": "5bbc9ca465f1b0fcd62362168a7c8831",
+ "seq": 9
+ },
+ {
+ "changes": [
+ {
+ "rev": "6-460637e73a6288cb24d532bf91f32969"
+ },
+ {
+ "rev": "5-eeaa298781f60b7bcae0c91bdedd1b87"
+ }
+ ],
+ "id": "729eb57437745e506b333068fff665ae",
+ "seq": 11
+ }
+ ]
+ }
+
.. versionchanged:: 0.11.0 added ``include_docs`` parameter
.. versionchanged:: 1.2.0 added ``view`` parameter and special value `_view`
@@ -104,6 +149,7 @@ Notes:
.. versionchanged:: 1.3.0 ``since`` parameter could take `now` value to start
listen changes since current seq number.
.. versionchanged:: 1.3.0 ``eventsource`` feed type added.
+.. versionchanged:: 1.4.0 Support ``Last-Event-ID`` header.
.. _changes:
@@ -146,23 +192,7 @@ including the given sequence number::
The return structure for ``normal`` and ``longpoll`` modes is a JSON
-array of changes objects, and the last update sequence number. The
-structure is described in the following table.
-
-+----------------------------------+-------------------------------------------+
-| Field | Description |
-+==================================+===========================================+
-| last_seq | Last change sequence number. |
-+----------------------------------+-------------------------------------------+
-| results [array] | Changes made to a database |
-+----------------------------------+-------------------------------------------+
-| changes [array] | List of changes, field-by-field, for this |
-| | document |
-+----------------------------------+-------------------------------------------+
-| id | Document ID |
-+----------------------------------+-------------------------------------------+
-| seq | Update sequence number |
-+----------------------------------+-------------------------------------------+
+array of changes objects, and the last update sequence number.
The return format for ``continuous`` mode the server sends a ``CRLF``
(carriage-return, linefeed) delimited line for each change. Each line