diff --git a/changelogs/client_server/newsfragments/1746.feature b/changelogs/client_server/newsfragments/1746.feature new file mode 100644 index 00000000..a3673074 --- /dev/null +++ b/changelogs/client_server/newsfragments/1746.feature @@ -0,0 +1 @@ +Add support for recursion on the /relations endpoints (MSC3981). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 0e7e8473..11023a33 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -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 +control how far the server recurses. If the client decides that the server's +recursion level is insufficient, it could, for example, perform the recursion +itself, 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 %}} diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index fc35bf5d..25c70199 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -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. @@ -39,6 +39,7 @@ paths: - $ref: '#/components/parameters/to' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/dir' + - $ref: '#/components/parameters/recurse' responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -96,6 +97,7 @@ paths: - $ref: '#/components/parameters/to' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/dir' + - $ref: '#/components/parameters/recurse' responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -167,6 +169,7 @@ paths: - $ref: '#/components/parameters/to' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/dir' + - $ref: '#/components/parameters/recurse' responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -294,6 +297,27 @@ components: example: org.example.my_relation schema: type: string + recurse: + in: query + name: recurse + x-addedInMatrixVersion: "1.10" + required: false + description: |- + Whether to additionally include events which only relate indirectly to the + given event, i.e. events related to the given event via two 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 homeservers traverse at least 3 levels of relationships. + Implementations may perform more but should be careful to not infinitely recurse. + + The default value is `false`. + schema: + type: boolean schemas: response: type: object @@ -308,6 +332,12 @@ components: 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. If the client + did not specify the `recurse` parameter, this field must be absent. responses: "404": description: |-