From 340f9e5ade4d5860baedcbb0fa6cce121604b426 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 7 Jun 2022 16:34:12 -0600 Subject: [PATCH] Copy/paste the endpoint to make Open API happy --- content/client-server-api/_index.md | 4 +- data/api/client-server/relations.yaml | 267 +++++++++++++++++++++++++- 2 files changed, 262 insertions(+), 9 deletions(-) diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index d136e351..91a6a11f 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -1980,7 +1980,9 @@ The endpoints where the server *should* include bundled aggregations are: * [`GET /rooms/{roomId}/messages`](#get_matrixclientv3roomsroomidmessages) * [`GET /rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid) * [`GET /rooms/{roomId}/event/{eventId}`](#get_matrixclientv3roomsroomideventeventid) -* [`GET /rooms/{roomId}/relations`](#get_matrixclientv3roomsroomidrelations) +* [`GET /rooms/{roomId}/relations/{eventId}`](#get_matrixclientv1roomsroomidrelationseventid) +* [`GET /rooms/{roomId}/relations/{eventId}/{relType}`](#get_matrixclientv1roomsroomidrelationseventidreltype) +* [`GET /rooms/{roomId}/relations/{eventId}/{relType}/{eventType}`](#get_matrixclientv1roomsroomidrelationseventidreltypeeventtype) * [`GET /sync`](#get_matrixclientv3sync) when the relevant section has a `limited` value of `true`. * [`POST /search`](#post_matrixclientv3search) for any matching events under `room_events`. diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 19cb2a4f..05f49d28 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -27,7 +27,7 @@ produces: securityDefinitions: $ref: definitions/security.yaml paths: - "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": + "/rooms/{roomId}/relations/{eventId}": get: summary: Get the child events for a given parent event. description: |- @@ -40,6 +40,129 @@ paths: The caller can use a `from` token from page 1 and a `to` token from page 2 to paginate forwards over the same range, however. operationId: getRelatingEvents + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The ID of the room containing the parent event. + required: true + x-example: "!636q39766251:matrix.org" + - in: path + type: string + name: eventId + description: The ID of the parent event whose child events are to be returned. + required: true + x-example: "$asfDuShaf7Gafaw" + - in: query + type: string + name: from + description: |- + The pagination token to start returning results from. If not supplied, results + start at the earliest topological event known to the server. + + Can be a `next_batch` or `prev_batch` token from a previous call, or a returned + `start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) + or `next_batch`/`prev_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). + required: false + x-example: "page2_token" + - in: query + type: string + name: to + description: |- + The pagination token to stop returning results at. If not supplied, results + continue up to `limit` or until there are no more events. + + Like `from`, this can be a previous token from a prior call to this endpoint + or from `/messages` or `/sync`. + required: false + x-example: "page3_token" + - in: query + type: integer + name: limit + description: |- + The maximum number of results to return in a single `chunk`. The server can + and should apply a maximum value to this parameter to avoid large responses. + + Similarly, the server should apply a default value when not supplied. + required: false + x-example: 20 + responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. + + 200: + description: |- + The paginated child events which point to the parent. If no events are + pointing to the parent or the pagination yields no results, an empty `chunk` + is returned. + examples: + application/json: { + "chunk": [{ + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + }], + "next_batch": "page2_token", + "prev_batch": "page1_token" + } + schema: + type: object + properties: + chunk: + title: "ChildEventsChunk" + type: array + description: |- + The child events of the requested event. If a `relType` or `eventType` was + supplied on the URL, the events returned will match those details. + items: + allOf: + - "$ref": "definitions/client_event.yaml" + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no prior results to fetch, i.e. this is the first batch/page. + required: ['chunk'] + 404: + description: |- + The parent event was not found or the user does not have permission to read + this event (it might be contained in history that is not accessible to the user). + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Event relationships + # The same as above, with added `/{relType}` + "/rooms/{roomId}/relations/{eventId}/{relType}": + get: + summary: Get the child events for a given parent event, with a given `relType`. + description: |- + Retrieve all of the child events for a given parent event which relate to the parent + using the given `relType`. + + Note that when paginating the `from` token must be *before* the `to` token, if + supplied. This means it's only possible to paginate "forwards" through events. + An example of an *invalid* call would be a `from` token from page 2 of the results, + and a `to` token from page 1: the server can't go backwards with this information. + The caller can use a `from` token from page 1 and a `to` token from page 2 to + paginate forwards over the same range, however. + operationId: getRelatingEventsWithRelType security: - accessToken: [] parameters: @@ -59,21 +182,148 @@ paths: type: string name: relType description: |- - The [relationship type](/client-server-api/#relationship-types) to search - for, if any. Exclude to find all child events which point to the supposed parent - event with any `rel_type`. - required: true # we can't say false, annoyingly + The [relationship type](/client-server-api/#relationship-types) to search for. + required: true + x-example: "org.example.my_relation" + - in: query + type: string + name: from + description: |- + The pagination token to start returning results from. If not supplied, results + start at the earliest topological event known to the server. + + Can be a `next_batch` or `prev_batch` token from a previous call, or a returned + `start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) + or `next_batch`/`prev_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). + required: false + x-example: "page2_token" + - in: query + type: string + name: to + description: |- + The pagination token to stop returning results at. If not supplied, results + continue up to `limit` or until there are no more events. + + Like `from`, this can be a previous token from a prior call to this endpoint + or from `/messages` or `/sync`. + required: false + x-example: "page3_token" + - in: query + type: integer + name: limit + description: |- + The maximum number of results to return in a single `chunk`. The server can + and should apply a maximum value to this parameter to avoid large responses. + + Similarly, the server should apply a default value when not supplied. + required: false + x-example: 20 + responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. + + 200: + description: |- + The paginated child events which point to the parent. If no events are + pointing to the parent or the pagination yields no results, an empty `chunk` + is returned. + examples: + application/json: { + "chunk": [{ + "room_id": "!636q39766251:matrix.org", + "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml", + "content": { + "m.relates_to": { + "rel_type": "org.example.my_relation", + "event_id": "$asfDuShaf7Gafaw" + } + } + }], + "next_batch": "page2_token", + "prev_batch": "page1_token" + } + schema: + type: object + properties: + chunk: + title: "ChildEventsChunk" + type: array + description: |- + The child events of the requested event. If a `relType` or `eventType` was + supplied on the URL, the events returned will match those details. + items: + allOf: + - "$ref": "definitions/client_event.yaml" + next_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no more results to fetch and the client should stop paginating. + prev_batch: + type: string + description: |- + An opaque string representing a pagination token. The absence of this token + means there are no prior results to fetch, i.e. this is the first batch/page. + required: ['chunk'] + 404: + description: |- + The parent event was not found or the user does not have permission to read + this event (it might be contained in history that is not accessible to the user). + examples: + application/json: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } + schema: + "$ref": "definitions/errors/error.yaml" + tags: + - Event relationships + # The same as above, with added `/{eventType}` + "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": + get: + summary: Get the child events for a given parent event, with a given `relType` and `eventType`. + description: |- + Retrieve all of the child events for a given parent event which relate to the parent + using the given `relType` and have the given `eventType`. + + Note that when paginating the `from` token must be *before* the `to` token, if + supplied. This means it's only possible to paginate "forwards" through events. + An example of an *invalid* call would be a `from` token from page 2 of the results, + and a `to` token from page 1: the server can't go backwards with this information. + The caller can use a `from` token from page 1 and a `to` token from page 2 to + paginate forwards over the same range, however. + operationId: getRelatingEventsWithRelTypeAndEventType + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The ID of the room containing the parent event. + required: true + x-example: "!636q39766251:matrix.org" + - in: path + type: string + name: eventId + description: The ID of the parent event whose child events are to be returned. + required: true + x-example: "$asfDuShaf7Gafaw" + - in: path + type: string + name: relType + description: |- + The [relationship type](/client-server-api/#relationship-types) to search for. + required: true x-example: "org.example.my_relation" - in: path type: string name: eventType description: |- - The event type of child events to search for, if any. Exclude to find all - child events of any type which point to the supposed parent event. + The event type of child events to search for. Note that in encrypted rooms this will typically always be `m.room.encrypted` regardless of the event type contained within the encrypted payload. - required: true # we can't say false, annoyingly + required: true x-example: "m.room.message" - in: query type: string @@ -168,3 +418,4 @@ paths: "$ref": "definitions/errors/error.yaml" tags: - Event relationships +