@ -1214,88 +1214,6 @@ using an `unstable` version.
When this capability is not listed, clients should use `"1"` as the
default and only stable `available` room version.
## Pagination
{{% boxes/note %}}
The paths referred to in this section are not actual endpoints. They
only serve as examples to explain how pagination functions.
{{% /boxes/note %}}
Pagination is the process of dividing a dataset into multiple discrete
pages. Matrix makes use of pagination to allow clients to view extremely
large datasets. These datasets are not limited to events in a room (for
example clients may want to paginate a list of rooms in addition to
events within those rooms). Regardless of what is being paginated, there
is a common approach which is used to give clients an easy way of
selecting subsets of a potentially changing dataset. Each endpoint that
uses pagination may use different parameters. However the theme among
them is that they take a `from` and `to` token, and occasionally a
`limit` and `dir` . Together, these parameters describe the position in a
data set, where `from` and `to` are known as "stream tokens" matching
the regular expression `[a-zA-Z0-9.=_-]+` . If supported, the `dir`
defines the direction of events to return: either forwards (`f`) or
backwards (`b`). The response may contain tokens that can be used for
retrieving results before or after the returned set. These tokens may be
called < span class = "title-ref" > start< / span > or < span
class="title-ref">prev\_batch</ span > for retrieving the previous result
set, or < span class = "title-ref" > end< / span > , < span
class="title-ref">next\_batch</ span > or < span
class="title-ref">next\_token</ span > for retrieving the next result set.
In the following examples, 'START' and 'END' are placeholders to signify
the start and end of the data sets respectively.
For example, if an endpoint had events E1 -> E15. The client wants
the last 5 events and doesn't know any previous events:
```
S E
|-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-|
| | |
| _____ | < --backwards-- |
|__________________ | | ________ |
| | | |
GET /somepath?to=START& limit=5& dir=b& from=END
Returns:
E15,E14,E13,E12,E11
```
Another example: a public room list has rooms R1 -> R17. The client
is showing 5 rooms at a time on screen, and is on page 2. They want to
now show page 3 (rooms R11 -> 15):
```
S E
| 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | stream token
|-R1-R2-R3-R4-R5-R6-R7-R8-R9-R10-R11-R12-R13-R14-R15-R16-R17| room
|____________| |________________|
| |
Currently |
viewing |
|
GET /roomslist?from=9& to=END& limit=5
Returns: R11,R12,R13,R14,R15
```
Note that tokens are treated in an *exclusive* , not inclusive, manner.
The end token from the initial request was '9' which corresponded to
R10. When the 2nd request was made, R10 did not appear again, even
though from=9 was specified. If you know the token, you already have the
data.
Responses for pagination-capable endpoints SHOULD have a `chunk` array
alongside the applicable stream tokens to represent the result set.
In general, when the end of a result set is reached the applicable
stream token will be excluded from the response. For example, if a user
was backwards-paginating events in a room they'd eventually reach the
first event in the room. In this scenario, the `prev_batch` token would
be excluded from the response. Some paginated endpoints are open-ended
in one direction, such as endpoints which expose an event stream for an
active room. In this case, it is not possible for the client to reach
the true "end" of the data set and therefore should always be presented
with a token to keep moving forwards.
## Filtering
Filters can be created on the server and can be passed as a parameter to
Richard van der Hoff
3 years ago
committed by