MSC3715: Add a pagination direction parameter to /relations

proposals/3715-relations-parity-messages.md

@@ -0,0 +1,72 @@
+# MSC3715: Add a pagination direction parameter to `/relations`
+
+[MSC2675](https://github.com/matrix-org/matrix-doc/pull/2675) introduced the
+`/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` parameter 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]`.
+
+In order to be backwards compatible with MSC2675 (and Synapse's legacy
+implementation), the `dir` parameter must be optional (defaulting to `b`). This
+differs from the specification of `/messages` where the `dir` parameter is
+required.[^1]
+
+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.
+
+Since this endpoint can now be used to paginate backwards over children events,
+it is also useful for the `from` parameter to accept `prev_batch` values from
+previous calls (as well as `next_batch` values, as is currently specified). The
+[definition of the `from` parameter](https://spec.matrix.org/unstable/client-server-api/#get_matrixclientv1roomsroomidrelationseventid)
+is updated:
+
+> Can be a `from_batch` token **or `next_batch`** token from a previous call, or a
+> returned `start` token from `/messages`, or a `next_batch` token from `/sync`.
+
+(Bold indicates new text.)
+## Potential issues
+
+`/messages` does have one additional parameter (`filter`) which would still not
+be implemented for `/relations`. It is unclear if this parameter is useful here.
+
+
+## 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.
+
+Instead of having a different default direction from `/messages`, a `v2` version
+could be added which accepts the `dir` parameter with the same default directionality
+as `/messages`, but the opposite of the current (`v1`) version of the endpoint.
+
+
+## Security considerations
+
+None.
+
+## Unstable prefix
+
+Before standardization, `org.matrix.msc3715.dir` should be used in place of `dir`.
+
+[^1]: Note that [Synapse's implementation](https://github.com/matrix-org/synapse/blob/10a88ba91cb16ccf757984f0a7d41ddf8b4dc07f/synapse/streams/config.py#L48)
+does not require a `dir` parameter for the `/messages` API and defaults to `f`
+if it is not provided.