|
|
|
@ -491,6 +491,100 @@ medium
|
|
|
|
|
address
|
|
|
|
|
The textual address of the 3pid, eg. the email address
|
|
|
|
|
|
|
|
|
|
Pagination
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
|
The paths referred to in this section are not actual endpoints. They only
|
|
|
|
|
serve as examples to explain how pagination functions.
|
|
|
|
|
|
|
|
|
|
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 underlying API which is used to
|
|
|
|
|
to give clients a consistent way of selecting subsets of a potentially changing
|
|
|
|
|
dataset. Requests pass in ``from``, ``to``, ``dir`` and ``limit`` parameters
|
|
|
|
|
which describe where to read from the stream. ``from`` and ``to`` are opaque
|
|
|
|
|
textual 'stream tokens' which describe the current position in the dataset.
|
|
|
|
|
The ``dir`` parameter is an enum representing the direction of events to return:
|
|
|
|
|
either ``f`` orwards or ``b`` ackwards. The response returns new ``start`` and
|
|
|
|
|
``end`` stream token values which can then be passed to subsequent requests to
|
|
|
|
|
continue pagination. Not all endpoints will make use of all the parameters
|
|
|
|
|
outlined here: see the specific endpoint in question for more information.
|
|
|
|
|
|
|
|
|
|
Pagination Request Query Parameters
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Query parameters:
|
|
|
|
|
from:
|
|
|
|
|
$streamtoken - The opaque token to start streaming from.
|
|
|
|
|
to:
|
|
|
|
|
$streamtoken - The opaque token to end streaming at. Typically,
|
|
|
|
|
clients will not know the item of data to end at, so this will usually be
|
|
|
|
|
omitted.
|
|
|
|
|
limit:
|
|
|
|
|
integer - An integer representing the maximum number of items to
|
|
|
|
|
return.
|
|
|
|
|
dir:
|
|
|
|
|
f|b - The direction to return events in. Typically this is ``b`` to paginate
|
|
|
|
|
backwards in time.
|
|
|
|
|
|
|
|
|
|
'START' and 'END' are placeholder values used in these examples to describe the
|
|
|
|
|
start and end of the dataset respectively.
|
|
|
|
|
|
|
|
|
|
Unless specified, the default pagination parameters are ``from=START``,
|
|
|
|
|
``to=END``, without a limit set.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Pagination Response
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Responses to pagination requests MUST follow the format::
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"chunk": [ ... , Responses , ... ],
|
|
|
|
|
"start" : $streamtoken,
|
|
|
|
|
"end" : $streamtoken
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Where $streamtoken is an opaque token which can be used in another query to
|
|
|
|
|
get the next set of results. The "start" and "end" keys can only be omitted if
|
|
|
|
|
the complete dataset is provided in "chunk".
|
|
|
|
|
|
|
|
|
|
Events
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
@ -563,8 +657,14 @@ returning early if an event occurs. Only the events API supports long-polling.
|
|
|
|
|
All events which are visible to the client will appear in the
|
|
|
|
|
events API. When the request returns, an ``end`` token is included in the
|
|
|
|
|
response. This token can be used in the next request to continue where the
|
|
|
|
|
last request left off. Multiple events can be returned per long-poll. All events
|
|
|
|
|
must be de-duplicated based on their event ID.
|
|
|
|
|
last request left off. Multiple events can be returned per long-poll.
|
|
|
|
|
|
|
|
|
|
.. Warning::
|
|
|
|
|
Events are ordered in this API according to the arrival time of the event on
|
|
|
|
|
the homeserver. This can conflict with other APIs which order events based on
|
|
|
|
|
their partial ordering in the event graph. This can result in duplicate events
|
|
|
|
|
being received (once per API call). Clients SHOULD de-duplicate events based
|
|
|
|
|
on the event ID when this happens.
|
|
|
|
|
|
|
|
|
|
.. TODO
|
|
|
|
|
is deduplication actually a hard requirement in CS v2?
|
|
|
|
@ -573,8 +673,8 @@ must be de-duplicated based on their event ID.
|
|
|
|
|
Do we ever support streaming requests? Why not websockets?
|
|
|
|
|
|
|
|
|
|
When the client first logs in, they will need to initially synchronise with
|
|
|
|
|
their home server. This is achieved via the initial sync API. This API also
|
|
|
|
|
returns an ``end`` token which can be used with the event stream.
|
|
|
|
|
their home server. This is achieved via the initial sync API described below.
|
|
|
|
|
This API also returns an ``end`` token which can be used with the event stream.
|
|
|
|
|
|
|
|
|
|
{{sync_http_api}}
|
|
|
|
|
|
|
|
|
@ -667,6 +767,9 @@ There are several APIs provided to ``GET`` events for a room:
|
|
|
|
|
|
|
|
|
|
{{rooms_http_api}}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
{{message_pagination_http_api}}
|
|
|
|
|
|
|
|
|
|
Redactions
|
|
|
|
|
~~~~~~~~~~
|
|
|
|
|
Since events are extensible it is possible for malicious users and/or servers
|
|
|
|
@ -712,105 +815,6 @@ The redaction event should be added under the key ``redacted_because``. When a
|
|
|
|
|
client receives a redaction event it should change the redacted event
|
|
|
|
|
in the same way a server does.
|
|
|
|
|
|
|
|
|
|
Pagination
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
.. NOTE::
|
|
|
|
|
The paths referred to in this section are not actual endpoints. They only
|
|
|
|
|
serve as examples to explain how pagination functions.
|
|
|
|
|
|
|
|
|
|
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 underlying API which is used to
|
|
|
|
|
to give clients a consistent way of selecting subsets of a potentially changing
|
|
|
|
|
dataset. Requests pass in ``from``, ``to``, ``dir`` and ``limit`` parameters
|
|
|
|
|
which describe where to read from the stream. ``from`` and ``to`` are opaque
|
|
|
|
|
textual 'stream tokens' which describe the current position in the dataset.
|
|
|
|
|
The ``dir`` parameter is an enum representing the direction of events to return:
|
|
|
|
|
either ``f`` orwards or ``b`` ackwards. The response returns new ``start`` and
|
|
|
|
|
``end`` stream token values which can then be passed to subsequent requests to
|
|
|
|
|
continue pagination. Not all endpoints will make use of all the parameters
|
|
|
|
|
outlined here: see the specific endpoint in question for more information.
|
|
|
|
|
|
|
|
|
|
Pagination Request Query Parameters
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Query parameters:
|
|
|
|
|
from:
|
|
|
|
|
$streamtoken - The opaque token to start streaming from.
|
|
|
|
|
to:
|
|
|
|
|
$streamtoken - The opaque token to end streaming at. Typically,
|
|
|
|
|
clients will not know the item of data to end at, so this will usually be
|
|
|
|
|
omitted.
|
|
|
|
|
limit:
|
|
|
|
|
integer - An integer representing the maximum number of items to
|
|
|
|
|
return.
|
|
|
|
|
dir:
|
|
|
|
|
f|b - The direction to return events in. Typically this is ``b`` to paginate
|
|
|
|
|
backwards in time.
|
|
|
|
|
|
|
|
|
|
'START' and 'END' are placeholder values used in these examples to describe the
|
|
|
|
|
start and end of the dataset respectively.
|
|
|
|
|
|
|
|
|
|
Unless specified, the default pagination parameters are ``from=START``,
|
|
|
|
|
``to=END``, without a limit set.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Pagination Response
|
|
|
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
Responses to pagination requests MUST follow the format::
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"chunk": [ ... , Responses , ... ],
|
|
|
|
|
"start" : $streamtoken,
|
|
|
|
|
"end" : $streamtoken
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Where $streamtoken is an opaque token which can be used in another query to
|
|
|
|
|
get the next set of results. The "start" and "end" keys can only be omitted if
|
|
|
|
|
the complete dataset is provided in "chunk".
|
|
|
|
|
|
|
|
|
|
Pagination APIs
|
|
|
|
|
~~~~~~~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
{{message_pagination_http_api}}
|
|
|
|
|
|
|
|
|
|
Rooms
|
|
|
|
|
-----
|
|
|
|
|
|
|
|
|
|