From 48e0783b5eebe4fcbbd4b92c76d81f65ff70359e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 25 Aug 2021 11:48:45 +0100 Subject: [PATCH] Clarifications to pagination parameters for various APIs (#3353) --- changelogs/client_server/3353.clarification | 1 + .../definitions/timeline_batch.yaml | 6 ++- .../api/client-server/message_pagination.yaml | 41 +++++++++++++------ data/api/client-server/notifications.yaml | 4 +- data/api/client-server/old_sync.yaml | 29 ++++++++----- data/api/client-server/room_initial_sync.yaml | 15 ++++--- data/api/client-server/sync.yaml | 3 +- 7 files changed, 67 insertions(+), 32 deletions(-) create mode 100644 changelogs/client_server/3353.clarification diff --git a/changelogs/client_server/3353.clarification b/changelogs/client_server/3353.clarification new file mode 100644 index 00000000000..79f15dc716a --- /dev/null +++ b/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`. \ No newline at end of file diff --git a/data/api/client-server/definitions/timeline_batch.yaml b/data/api/client-server/definitions/timeline_batch.yaml index 65a7622a12a..35632562895 100644 --- a/data/api/client-server/definitions/timeline_batch.yaml +++ b/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//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 diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index 5b86ce9014a..c3c8d8882b1 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/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, - or from a `start` or `end` token returned by a previous request - to this endpoint. + from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint, + or from an `end` token returned by a previous request 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, - or from a `start` or `end` token returned by a previous request to - this endpoint. + a `prev_batch` or `next_batch` token returned by the `/sync` endpoint, + or from an `end` token returned by a previous request to 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 - the token supplied in `from`. + A token corresponding to the start of `chunk`. This will be the same as + the value given in `from`. end: type: string description: |- - The token the pagination ends at. If `dir=b` this token should - be used again to request even earlier events. + A token corresponding to the end of `chunk`. This token can be passed + 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 - at the `from` point. + for `dir=f` in chronological order. (The exact definition of `chronological` + 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", diff --git a/data/api/client-server/notifications.yaml b/data/api/client-server/notifications.yaml index 7d017403751..0176a9b4d00 100644 --- a/data/api/client-server/notifications.yaml +++ b/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 diff --git a/data/api/client-server/old_sync.yaml b/data/api/client-server/old_sync.yaml index 522f0b1a459..d961077be5a 100644 --- a/data/api/client-server/old_sync.yaml +++ b/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 - token should be used with the `/events` API to listen for new + A token which correlates to the end of the timelines returned. This + 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`. - Used for pagination. + A token which correlates to the start of `chunk`. + Can be passed to + [`/rooms//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`. - Used for pagination. + A token which correlates to the end of `chunk`. + Can be passed to + [`/rooms//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: |- diff --git a/data/api/client-server/room_initial_sync.yaml b/data/api/client-server/room_initial_sync.yaml index bab0e3d92cc..f8660e69f32 100644 --- a/data/api/client-server/room_initial_sync.yaml +++ b/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`. - Used for pagination. + A token which correlates to the start of `chunk`. Can be passed to + [`/rooms//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`. - Used for pagination. + A token which correlates to the end of `chunk`. Can be passed to + [`/rooms//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: |- diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index 140843a0c4a..53c521737ca 100644 --- a/data/api/client-server/sync.yaml +++ b/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