couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From kxe...@apache.org
Subject [21/50] git commit: updated refs/heads/1781-reorganize-and-improve-docs to 360107b
Date Wed, 21 Aug 2013 16:37:48 GMT
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 <kxepal@apache.org>
Authored: Mon Aug 12 05:24:49 2013 +0400
Committer: Alexander Shorin <kxepal@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


Mime
View raw message