From 925a44d901ab3366da5efcf8373d634fb688fe51 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 19 Aug 2021 19:05:53 +0100 Subject: [PATCH 1/4] Clarifications to pagination parameters for various APIs --- .../definitions/timeline_batch.yaml | 6 +++- .../api/client-server/message_pagination.yaml | 36 ++++++++++++------- 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 +- 6 files changed, 61 insertions(+), 32 deletions(-) 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..1e6b9ab39ac 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -51,9 +51,8 @@ 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. required: true x-example: "s345_678_333" - in: query @@ -61,16 +60,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 +97,28 @@ 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. + + 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 +134,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 From 84a333e123ed10077bfbb2fae8036ad4a080fd63 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Thu, 19 Aug 2021 19:08:32 +0100 Subject: [PATCH 2/4] changelog --- changelogs/client_server/3353.clarification | 1 + 1 file changed, 1 insertion(+) 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 From ac30b33b9cf1b6ed6c9c360f6976fe4303e29ae9 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 24 Aug 2021 09:41:44 +0100 Subject: [PATCH 3/4] additional clarifications to `/messages` --- data/api/client-server/message_pagination.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index 1e6b9ab39ac..bb3de2a5852 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -53,6 +53,10 @@ paths: The token to start returning events from. This token can be obtained 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. + + Some server implementations also accept a value returned as a `start` token + by a previous request to this endpoint, but this is not required, and + clients should not rely on it. required: true x-example: "s345_678_333" - in: query @@ -114,7 +118,8 @@ paths: 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. + 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 From 5e3d640bb3a0c0418d29b4dd7c66f46cfebc339f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 25 Aug 2021 11:47:11 +0100 Subject: [PATCH 4/4] Update data/api/client-server/message_pagination.yaml --- data/api/client-server/message_pagination.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/data/api/client-server/message_pagination.yaml b/data/api/client-server/message_pagination.yaml index bb3de2a5852..c3c8d8882b1 100644 --- a/data/api/client-server/message_pagination.yaml +++ b/data/api/client-server/message_pagination.yaml @@ -54,9 +54,9 @@ paths: 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. - Some server implementations also accept a value returned as a `start` token - by a previous request to this endpoint, but this is not required, and - clients should not rely on it. + 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