Skip to content

MSC3715: Add a pagination direction parameter to /relations #3715

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

Merged
merged 13 commits into from
Sep 20, 2022
Merged

MSC3715: Add a pagination direction parameter to /relations #3715

Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8fd9ac3
Add MSC for dir & filter on /relations.
clokep Feb 7, 2022
afb882b
Fix typo.
clokep Feb 7, 2022
17cc780
Simplify additional parameters.
clokep Feb 8, 2022
f7f92a1
Add alternative.
clokep Feb 8, 2022
08f85e3
Add an unstable prefix.
clokep Feb 11, 2022
b3007ce
Move note about backwards compat.
clokep Mar 9, 2022
d80dad9
Add a link.
clokep Mar 9, 2022
b343651
Clarify proposal.
clokep Apr 5, 2022
6f4a77c
Re-title MSC
clokep Apr 6, 2022
53590c3
Document another alternative.
clokep Jun 13, 2022
703ccc1
Add note about prev_batch token.
clokep Jun 13, 2022
5620bb1
Clarifications from review.
clokep Jul 19, 2022
defb0dc
Flesh out description.
clokep Sep 14, 2022
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
47 changes: 47 additions & 0 deletions proposals/3715-relations-parity-messages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# MSC3715: `/relations` partiy with `/messages`

[MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) introduced the
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm unsure it is worth including in this MSC (I don't think it is), but older versions of MSC2675 did include a dir parameter that was then dropped. matrix-org/synapse#11926 has some of the archaeology, but I'm not sure it is particularly interesting besides "we're not sure this is useful". It turns out that it was a surprise that these parameters were not supported and that it is useful if they are.

I can include more context here in the MSC if necessary, but I think letting this MSC stand on its own is probably better.

`/relations` API as an endpoint to paginate over the relations of an event. It
is described as behaving like the `/messages` API, but is missing parameters
to fully achieve that.


## Proposal

Two new parameters be added to the `/relations` API for parity with `/messages`,
both [parameters have the same as definition as for `/messages`](https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidmessages),
which are copied below:

* `dir`: 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* chronological order, again starting at `from`.

One of: `[b f]`.
* `filter`: A JSON RoomEventFilter to filter returned events with.

The rationale for both of these is parity between endpoints, which makes the
overall specification easier to reason about. Additionally, these parameters
make it easier to request missing relation information without needed to paginate
through known information -- this is particularly needed for mobile or
low-bandwidth devices where it is desired to keep the round-trips to the server
to a minimum.


## Potential issues

The `dir` parameter needs to be optional (defaulting to `b`) to be backwards
compatible with MSC2675 (and Synapse's legacy implementation).


## Alternatives

None.


## Security considerations

None.

## Unstable prefix

None, assuming that this lands in the same Matrix specification version as MSC2675.