Clarifications to pagination parameters for various APIs (#3353)

changelogs/client_server/3353.clarification

@@ -0,0 +1 @@
+Clarify the documentation around the pagination tokens used by `/sync`, `/rooms/{room_id}/messages`, `/initialSync`, `/rooms/{room_id}/initialSync`, and `/notifications`.

data/api/client-server/definitions/timeline_batch.yaml

@@ -21,7 +21,11 @@ properties:
     type: boolean
   prev_batch:
     description: A token that can be supplied to the `from` parameter of the
-      rooms/{roomId}/messages endpoint.
+      [`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
+      endpoint in order to retrieve earlier events.
+
+      If no earlier events are available, this property may be omitted from
+      the response.
     type: string
 type: object
 title: TimelineBatch

data/api/client-server/message_pagination.yaml

@@ -51,9 +51,12 @@ paths:
           name: from
           description: |-
             The token to start returning events from. This token can be obtained
-            from a `prev_batch` token returned for each room by the sync API,
+            from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
-            or from a `start` or `end` token returned by a previous request
+            or from an `end` token returned by a previous request to this endpoint.
-            to this endpoint.
+
+            This endpoint can also accept a value returned as a `start` token
+            by a previous request to this endpoint, though servers are not 
+            required to support this. Clients should not rely on the behaviour.
           required: true
           x-example: "s345_678_333"
         - in: query
@@ -61,16 +64,18 @@ paths:
           name: to
           description: |-
             The token to stop returning events at. This token can be obtained from
-            a `prev_batch` token returned for each room by the sync endpoint,
+            a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
-            or from a `start` or `end` token returned by a previous request to
+            or from an `end` token returned by a previous request to this endpoint.
-            this endpoint.
           required: false
         - in: query
           type: string
           enum: ["b", "f"]
           name: dir
           description: |-
-            The direction to return events from.
+            The direction to return events from. If this is set to `f`, events
+            will be returned in chronological order starting at `from`. If it
+            is set to `b`, events will be returned in *reverse* chronolgical
+            order, again starting at `from`.
           required: true
           x-example: "b"
         - in: query
@@ -96,20 +101,29 @@ paths:
               start:
                 type: string
                 description: |-
-                  The token the pagination starts from. If `dir=b` this will be
+                  A token corresponding to the start of `chunk`. This will be the same as
-                  the token supplied in `from`.
+                  the value given in `from`.
               end:
                 type: string
                 description: |-
-                  The token the pagination ends at. If `dir=b` this token should
+                  A token corresponding to the end of `chunk`. This token can be passed
-                  be used again to request even earlier events.
+                  back to this endpoint to request further events.
+
+                  If no further events are available (either because we have
+                  reached the start of the timeline, or because the user does
+                  not have permission to see any more events), this property
+                  is omitted from the response.
               chunk:
                 type: array
                 description: |-
                   A list of room events. The order depends on the `dir` parameter.
                   For `dir=b` events will be in reverse-chronological order,
-                  for `dir=f` in chronological order, so that events start
+                  for `dir=f` in chronological order. (The exact definition of `chronological`
-                  at the `from` point.
+                  is dependent on the server implementation.)
+
+                  Note that an empty `chunk` does not *necessarily* imply that no more events
+                  are available. Clients should continue to paginate until no `end` property
+                  is returned.
                 items:
                   "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
               state:
@@ -125,6 +139,7 @@ paths:
                   the membership of those members has not changed.
                 items:
                   $ref: "../../event-schemas/schema/core-event-schema/state_event.yaml"
+            required: [start, chunk]
           examples:
             application/json: {
                 "start": "t47429-4392820_219380_26003_2265",

data/api/client-server/notifications.yaml

@@ -41,7 +41,9 @@ paths:
         - in: query
           type: string
           name: from
-          description: Pagination token given to retrieve the next set of events.
+          description: |-
+            Pagination token to continue from. This should be the `next_token`
+            returned from an earlier call to this endpoint.
           required: false
           x-example: "xxxxx"
         - in: query

data/api/client-server/old_sync.yaml

@@ -36,7 +36,7 @@ paths:
 
         This endpoint was deprecated in r0 of this specification. Clients
         should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync)
-        API with a `since` parameter. See
+        endpoint with a `since` parameter. See
         the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: getEvents
       security:
@@ -73,12 +73,12 @@ paths:
               start:
                 type: string
                 description: |-
-                  A token which correlates to the first value in `chunk`. This
+                  A token which correlates to the start of `chunk`. This
                   is usually the same token supplied to `from=`.
               end:
                 type: string
                 description: |-
-                  A token which correlates to the last value in `chunk`. This
+                  A token which correlates to the end of `chunk`. This
                   token should be used in the next request to `/events`.
               chunk:
                 type: array
@@ -102,7 +102,7 @@ paths:
 
         This endpoint was deprecated in r0 of this specification. Clients
         should instead call the [`/sync`](/client-server-api/#get_matrixclientr0sync)
-        API with no `since` parameter. See
+        endpoint with no `since` parameter. See
         the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
       operationId: initialSync
       security:
@@ -199,8 +199,8 @@ paths:
               end:
                 type: string
                 description: |-
-                  A token which correlates to the last value in `chunk`. This
+                  A token which correlates to the end of the timelines returned. This
-                  token should be used with the `/events` API to listen for new
+                  token should be used with the `/events` endpoint to listen for new
                   events.
               presence:
                 type: array
@@ -237,13 +237,20 @@ paths:
                         start:
                           type: string
                           description: |-
-                            A token which correlates to the first value in `chunk`.
+                            A token which correlates to the start of `chunk`.
-                            Used for pagination.
+                            Can be passed to
+                            [`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
+                            to retrieve earlier events.
+
+                            If no earlier events are available, this property may be omitted from
+                            the response.
                         end:
                           type: string
                           description: |-
-                            A token which correlates to the last value in `chunk`.
+                            A token which correlates to the end of `chunk`.
-                            Used for pagination.
+                            Can be passed to
+                            [`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
+                            to retrieve later events.
                         chunk:
                           type: array
                           description: |-
@@ -257,7 +264,7 @@ paths:
                             title: RoomEvent
                             allOf:
                               - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
-                      required: ["start", "end", "chunk"]
+                      required: ["end", "chunk"]
                     state:
                       type: array
                       description: |-

data/api/client-server/room_initial_sync.yaml

@@ -98,13 +98,18 @@ paths:
                   start:
                     type: string
                     description: |-
-                      A token which correlates to the first value in `chunk`.
+                      A token which correlates to the start of `chunk`. Can be passed to
-                      Used for pagination.
+                      [`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
+                      to retrieve earlier events.
+
+                      If no earlier events are available, this property may be omitted from
+                      the response.
                   end:
                     type: string
                     description: |-
-                      A token which correlates to the last value in `chunk`.
+                      A token which correlates to the end of `chunk`. Can be passed to
-                      Used for pagination.
+                      [`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
+                      to retrieve later events.
                   chunk:
                     type: array
                     description: |-
@@ -118,7 +123,7 @@ paths:
                       title: RoomEvent
                       allOf:
                         - "$ref": "../../event-schemas/schema/core-event-schema/room_event.yaml"
-                required: ["start", "end", "chunk"]
+                required: ["end", "chunk"]
               state:
                 type: array
                 description: |-

data/api/client-server/sync.yaml

@@ -73,7 +73,8 @@ paths:
           name: since
           type: string
           description: |-
-            A point in time to continue a sync from.
+            A point in time to continue a sync from. This should be the
+            `next_batch` token returned by an earlier call to this endpoint.
           x-example: "s72594_4483_1934"
         - in: query
           name: full_state