Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarifications to pagination parameters for various APIs #3353

Merged
merged 4 commits into from
Aug 25, 2021
+67 −32
Merged

Clarifications to pagination parameters for various APIs #3353

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
925a44d
Clarifications to pagination parameters for various APIs
richvdh Aug 19, 2021
84a333e
changelog
richvdh Aug 19, 2021
ac30b33
additional clarifications to `/messages`
richvdh Aug 24, 2021
5e3d640
Update data/api/client-server/message_pagination.yaml
richvdh Aug 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/3353.clarification
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Clarify the documentation around the pagination tokens used by `/sync`, `/rooms/{room_id}/messages`, `/initialSync`, `/rooms/{room_id}/initialSync`, and `/notifications`.
6 changes: 5 additions & 1 deletion data/api/client-server/definitions/timeline_batch.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
36 changes: 23 additions & 13 deletions data/api/client-server/message_pagination.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,26 +51,27 @@ 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.
richvdh marked this conversation as resolved.
Show resolved Hide resolved
required: true
x-example: "s345_678_333"
- in: query
type: string
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`.
turt2live marked this conversation as resolved.
Show resolved Hide resolved
required: true
x-example: "b"
- in: query
Expand All @@ -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:
Expand All @@ -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",
Expand Down
4 changes: 3 additions & 1 deletion data/api/client-server/notifications.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 18 additions & 11 deletions data/api/client-server/old_sync.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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/<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`.
Used for pagination.
A token which correlates to the end of `chunk`.
Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
to retrieve later events.
chunk:
type: array
description: |-
Expand All @@ -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: |-
Expand Down
15 changes: 10 additions & 5 deletions data/api/client-server/room_initial_sync.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<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`.
Used for pagination.
A token which correlates to the end of `chunk`. Can be passed to
[`/rooms/<room_id>/messages`](#get_matrixclientr0roomsroomidmessages)
to retrieve later events.
chunk:
type: array
description: |-
Expand All @@ -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: |-
Expand Down
3 changes: 2 additions & 1 deletion data/api/client-server/sync.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down