Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-02-25 15:33:42 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Add dir parameter to pagination. Remove path references

Browse source 
This section needs a lot of work to not lie.
This commit is contained in:
Kegan Dougal 2015-10-14 09:58:03 +01:00
parent e561a663d3
commit e716e81963
1 changed files with 17 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
specification/1-client_server_api.rst
View file

@ -348,11 +348,13 @@ Pagination
Querying large datasets in Matrix always uses the same pagination API pattern to Querying large datasets in Matrix always uses the same pagination API pattern to
to give clients a consistent way of selecting subsets of a potentially changing to give clients a consistent way of selecting subsets of a potentially changing
dataset. Requests pass in ``from``, ``to`` and ``limit`` parameters which describe dataset. Requests pass in ``from``, ``to``, ``dir`` and ``limit`` parameters
where to read from the stream. ``from`` and ``to`` are opaque textual 'stream which describe where to read from the stream. ``from`` and ``to`` are opaque
tokens' which describe positions in the dataset. The response returns new textual 'stream tokens' which describe the current position in the dataset.
``start`` and ``end`` stream token values which can then be passed to subsequent The ``dir`` parameter is an enum representing the direction of events to return:
requests to continue pagination. 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.
Pagination Request Query Parameters Pagination Request Query Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -367,24 +369,26 @@ Query parameters:
limit: limit:
integer - An integer representing the maximum number of items to integer - An integer representing the maximum number of items to
return. 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' are placeholder values used in these examples to describe the
start and end of the dataset respectively. start and end of the dataset respectively.
Unless specified, the default pagination parameters are from=START, to=END, Unless specified, the default pagination parameters are ``from=START``,
without a limit set. This allows you to hit an API like ``to=END``, without a limit set.
/events without any query parameters to get everything.
For example, the event stream has events E1 -> E15. The client wants the last 5 For example, if an endpoint had events E1 -> E15. The client wants the last 5
events and doesn't know any previous events:: events and doesn't know any previous events::
S E S E
|-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-| |-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-|
| | | | | |
| _____| | | _____| |
|__________________ | ___________________| |__________________ | _______________|
| | | | | |
GET /events?to=START&limit=5&from=END GET /somepath?to=START&limit=5&from=END
Returns: Returns:
E15,E14,E13,E12,E11 E15,E14,E13,E12,E11
@ -401,7 +405,7 @@ now show page 3 (rooms R11 -> 15)::
Currently | Currently |
viewing | viewing |
| |
GET /rooms/list?from=9&to=END&limit=5 GET /roomslist?from=9&to=END&limit=5
Returns: R11,R12,R13,R14,R15 Returns: R11,R12,R13,R14,R15
Note that tokens are treated in an *exclusive*, not inclusive, manner. The end Note that tokens are treated in an *exclusive*, not inclusive, manner. The end