wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Clarifications to pagination parameters for various APIs (#3353)

Browse source
This commit is contained in:
Richard van der Hoff 2021-08-25 11:48:45 +01:00 • committed by Richard van der Hoff
parent 4b2bbbabcc
commit 6bd7b6cbb5
7 changed files with 67 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

6
data/api/client-server/definitions/timeline_batch.yaml
View file

@ -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

41
data/api/client-server/message_pagination.yaml
View file

@ -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",

4
data/api/client-server/notifications.yaml
View file

@ -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

29
data/api/client-server/old_sync.yaml
View file

@ -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/<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: |-
@ -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: |-

15
data/api/client-server/room_initial_sync.yaml
View file

@ -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: |-
@ -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: |-

3
data/api/client-server/sync.yaml
View file

@ -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