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 5 commits
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
54 changes: 54 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,54 @@
# MSC3715: `/relations` parity 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

It is proposed to add the `dir`to the `/relations` API for parity with `/messages`,
it will [have the same as definition as for `/messages`](https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidmessages),
which is copied below:

> 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]`.

Including the `dir` parameter will 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.

It is additionally useful to unify similar endpoints as much as possible to avoid
surprises for developers.


## Potential issues

Unlike for `/messages`, the `dir` parameter for `/relations` needs to be optional
(defaulting to `b`) to be backwards compatible with MSC2675 (and Synapse's
legacy implementation).

`/messages` does have one additional parameter (`filter`) which would still not
be implemented for `/relations`. It is unclear if this parameter is useful here.
Comment on lines +84 to +85
Copy link
Member

Choose a reason for hiding this comment

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

let's leave it out until we have a usecase.



## Alternatives

The endpoint could be replaced with the `/event_relationships` API proposed in
[MSC2836](https://github.com/matrix-org/matrix-doc/pull/2836). That API would
add significant complexity over the current `/relations` API (e.g. arbitrary
of relations) and is not necessary to simply iterate events in the reverse ordering.


## Security considerations

None.

## Unstable prefix

Before standardization, `org.matrix.msc3715.dir` should be used in place of `dir`.