Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-23 11:34:09 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Spec for MSC3981

Browse source 
This writes up https://github.com/matrix-org/matrix-spec-proposals/pull/3981

Hopefully this is relatively straightforward, apart from having to add
the parameters and response field in all three places. I tried to factor
these out but it seems references just aren't supported in the right
places currently (see https://github.com/matrix-org/matrix-spec/pull/1745
for my efforts). Path parameters can't be optional, so it can't be done
that way either.
This commit is contained in:
David Baker 2024-03-12 17:38:07 +00:00
parent 9068c336f4
commit 4fde94767f
2 changed files with 88 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
content/client-server-api/_index.md
View file

@ -2156,6 +2156,19 @@ following endpoint.
This endpoint is particularly useful if the client has lost context on the aggregation for
a parent event and needs to rebuild/verify it.
When using the `recurse` parameter, note that there no way for a client to
affect how much the server recurses. If the client decides that the server's
recursion level is insufficient, it could, for example, perform the recursion
manually, or disable whatever feature requires more recursion.
Filters specified via `event_type` or `rel_type` will be applied to all events
returned, whether direct or indirect relations. Events that would match the filter,
but whose only relation to the original given event is through a non-matching
intermediate event, will not be included. This means that supplying a `rel_type`
parameter of `m.thread` is not appropriate for fetching all events in a thread since
relations to the threaded events would be filtered out. For this purpose, clients should
omit the `rel_type` parameter and perform any necessary filtering on the client side.
{{% boxes/note %}}
Because replies do not use `rel_type`, they will not be accessible via this API.
{{% /boxes/note %}}

76
data/api/client-server/relations.yaml
View file

@ -1,4 +1,4 @@
# Copyright 2022 The Matrix.org Foundation C.I.C.
# Copyright 2022,2024 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -96,6 +96,26 @@ paths:
enum:
- b
- f
- in: query
name: recurse
x-addedInMatrixVersion: "1.10"
required: false
description: |-
Whether to additionally include events which only relate indirectly to the
given event, ie. events related to the root events via one or more direct relationships.
If set to `false`, only events which have direct a relation with the given
event will be included.
If set to `true`, all events which relate to the given event, or relate to
events that relate to the given event, will be included.
It is recommended that at least 3 levels of relationships are traversed.
Implementations may perform more but should be careful to not infinitely recurse.
The default value is `false`.
schema:
type: boolean
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
@ -127,6 +147,12 @@ paths:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
recursion_depth:
type: integer
description: |-
If the `recurse` parameter was supplied by the client, this response field is
mandatory and gives the actual depth to which the server recursed. The the client
did not specify the `recurse` parameter, this field must be absent.
required:
- chunk
examples:
@ -253,6 +279,24 @@ paths:
enum:
- b
- f
- in: query
name: recurse
x-addedInMatrixVersion: "1.10"
required: false
description: |-
Whether to additionally include events which only relate indirectly to the
given event, ie. events related to the root events via one or more direct relationships.
If set to `false`, only events which have direct a relation with the given
event will be included.
If set to `true`, all events which relate to the given event, or relate to
events that relate to the given event, will be included.
It is recommended that at least 3 levels of relationships are traversed.
Implementations may perform more but should be careful to not infinitely recurse.
The default value is `false`.
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
@ -286,6 +330,12 @@ paths:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
recursion_depth:
type: integer
description: |-
If the `recurse` parameter was supplied by the client, this response field is
mandatory and gives the actual depth to which the server recursed. The the client
did not specify the `recurse` parameter, this field must be absent.
required:
- chunk
examples:
@ -424,6 +474,24 @@ paths:
enum:
- b
- f
- in: query
name: recurse
x-addedInMatrixVersion: "1.10"
required: false
description: |-
Whether to additionally include events which only relate indirectly to the
given event, ie. events related to the root events via one or more direct relationships.
If set to `false`, only events which have direct a relation with the given
event will be included.
If set to `true`, all events which relate to the given event, or relate to
events that relate to the given event, will be included.
It is recommended that at least 3 levels of relationships are traversed.
Implementations may perform more but should be careful to not infinitely recurse.
The default value is `false`.
responses:
# note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included.
@ -457,6 +525,12 @@ paths:
description: |-
An opaque string representing a pagination token. The absence of this token
means this is the start of the result set, i.e. this is the first batch/page.
recursion_depth:
type: integer
description: |-
If the `recurse` parameter was supplied by the client, this response field is
mandatory and gives the actual depth to which the server recursed. The the client
did not specify the `recurse` parameter, this field must be absent.
required:
- chunk
examples: