From bb4003afa8eaad8c6aab247785ddc1da35b1c268 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 19 Mar 2024 17:03:44 +0000 Subject: [PATCH] Factor out all the common parameters of the various /relations apis (#1745) Contributed by @zecakeh https://github.com/zecakeh/matrix-spec/commit/bd5478105213036b7bf313754d05a32fc97db648. Co-authored-by: Richard van der Hoff --- .../internal/newsfragments/1745.clarification | 1 + data/api/client-server/relations.yaml | 557 ++++++------------ 2 files changed, 196 insertions(+), 362 deletions(-) create mode 100644 changelogs/internal/newsfragments/1745.clarification diff --git a/changelogs/internal/newsfragments/1745.clarification b/changelogs/internal/newsfragments/1745.clarification new file mode 100644 index 00000000..acd85892 --- /dev/null +++ b/changelogs/internal/newsfragments/1745.clarification @@ -0,0 +1 @@ +Factor out all the common parameters of the various `/relations` apis. diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 65c3491a..fc35bf5d 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -33,69 +33,12 @@ paths: security: - accessToken: [] parameters: - - in: path - name: roomId - description: The ID of the room containing the parent event. - required: true - example: "!636q39766251:matrix.org" - schema: - type: string - - in: path - name: eventId - description: The ID of the parent event whose child events are to be returned. - required: true - example: $asfDuShaf7Gafaw - schema: - type: string - - in: query - name: from - description: |- - The pagination token to start returning results from. If not supplied, results - start at the most recent topological event known to the server. - - Can be a `next_batch` or `prev_batch` token from a previous call, or a returned - `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), - or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). - required: false - example: page2_token - schema: - type: string - - in: query - 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 - example: page3_token - schema: - type: string - - in: query - 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 - example: 20 - schema: - type: integer - - in: query - name: dir - x-addedInMatrixVersion: "1.4" - description: |- - Optional (default `b`) 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`. - schema: - type: string - enum: - - b - - f + - $ref: '#/components/parameters/roomId' + - $ref: '#/components/parameters/eventId' + - $ref: '#/components/parameters/from' + - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/dir' responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -107,60 +50,24 @@ paths: content: application/json: schema: - type: object - properties: - chunk: - title: ChildEventsChunk - type: array - description: The child events of the requested event, ordered topologically - most-recent first. - 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 this is the start of the result set, i.e. this is the first batch/page. - required: - - chunk + allOf: + - $ref: '#/components/schemas/response' + - type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: The child events of the requested event, ordered topologically + most-recent first. + items: + $ref: definitions/client_event.yaml + required: + - chunk examples: response: - value: { - "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" - } + $ref: '#/components/examples/response' "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). - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } + $ref: '#/components/responses/404' tags: - Event relationships # The same as above, with added `/{relType}` @@ -182,77 +89,13 @@ paths: security: - accessToken: [] parameters: - - in: path - name: roomId - description: The ID of the room containing the parent event. - required: true - example: "!636q39766251:matrix.org" - schema: - type: string - - in: path - name: eventId - description: The ID of the parent event whose child events are to be returned. - required: true - example: $asfDuShaf7Gafaw - schema: - type: string - - in: path - name: relType - description: The [relationship type](/client-server-api/#relationship-types) to - search for. - required: true - example: org.example.my_relation - schema: - type: string - - in: query - name: from - description: |- - The pagination token to start returning results from. If not supplied, results - start at the most recent topological event known to the server. - - Can be a `next_batch` or `prev_batch` token from a previous call, or a returned - `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), - or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). - required: false - example: page2_token - schema: - type: string - - in: query - 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 - example: page3_token - schema: - type: string - - in: query - 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 - example: 20 - schema: - type: integer - - in: query - name: dir - x-addedInMatrixVersion: "1.4" - description: |- - Optional (default `b`) 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`. - schema: - type: string - enum: - - b - - f + - $ref: '#/components/parameters/roomId' + - $ref: '#/components/parameters/eventId' + - $ref: '#/components/parameters/relType' + - $ref: '#/components/parameters/from' + - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/dir' responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -264,62 +107,26 @@ paths: content: application/json: schema: - type: object - properties: - chunk: - title: ChildEventsChunk - type: array - description: |- - The child events of the requested event, ordered topologically - most-recent first. The events returned will match the `relType` - supplied in the URL. - 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 this is the start of the result set, i.e. this is the first batch/page. - required: - - chunk + allOf: + - $ref: '#/components/schemas/response' + - type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: |- + The child events of the requested event, ordered topologically + most-recent first. The events returned will match the `relType` + supplied in the URL. + items: + $ref: definitions/client_event.yaml + required: + - chunk examples: response: - value: { - "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" - } + $ref: '#/components/examples/response' "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). - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } + $ref: '#/components/responses/404' tags: - Event relationships # The same as above, with added `/{eventType}` @@ -342,28 +149,9 @@ paths: security: - accessToken: [] parameters: - - in: path - name: roomId - description: The ID of the room containing the parent event. - required: true - example: "!636q39766251:matrix.org" - schema: - type: string - - in: path - name: eventId - description: The ID of the parent event whose child events are to be returned. - required: true - example: $asfDuShaf7Gafaw - schema: - type: string - - in: path - name: relType - description: The [relationship type](/client-server-api/#relationship-types) to - search for. - required: true - example: org.example.my_relation - schema: - type: string + - $ref: '#/components/parameters/roomId' + - $ref: '#/components/parameters/eventId' + - $ref: '#/components/parameters/relType' - in: path name: eventType description: |- @@ -375,55 +163,10 @@ paths: example: m.room.message schema: type: string - - in: query - name: from - description: |- - The pagination token to start returning results from. If not supplied, results - start at the most recent topological event known to the server. - - Can be a `next_batch` or `prev_batch` token from a previous call, or a returned - `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), - or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). - required: false - example: page2_token - schema: - type: string - - in: query - 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 - example: page3_token - schema: - type: string - - in: query - 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 - example: 20 - schema: - type: integer - - in: query - name: dir - x-addedInMatrixVersion: "1.4" - description: |- - Optional (default `b`) 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`. - schema: - type: string - enum: - - b - - f + - $ref: '#/components/parameters/from' + - $ref: '#/components/parameters/to' + - $ref: '#/components/parameters/limit' + - $ref: '#/components/parameters/dir' responses: # note: this endpoint deliberately does not support rate limiting, therefore a # 429 error response is not included. @@ -435,62 +178,26 @@ paths: content: application/json: schema: - type: object - properties: - chunk: - title: ChildEventsChunk - type: array - description: |- - The child events of the requested event, ordered topologically most-recent - first. The events returned will match the `relType` and `eventType` supplied - in the URL. - 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 this is the start of the result set, i.e. this is the first batch/page. - required: - - chunk + allOf: + - $ref: '#/components/schemas/response' + - type: object + properties: + chunk: + title: ChildEventsChunk + type: array + description: |- + The child events of the requested event, ordered topologically most-recent + first. The events returned will match the `relType` and `eventType` supplied + in the URL. + items: + $ref: definitions/client_event.yaml + required: + - chunk examples: response: - value: { - "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" - } + $ref: '#/components/examples/response' "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). - content: - application/json: - schema: - $ref: definitions/errors/error.yaml - examples: - response: - value: { - "errcode": "M_NOT_FOUND", - "error": "Event not found." - } + $ref: '#/components/responses/404' tags: - Event relationships servers: @@ -508,3 +215,129 @@ servers: components: securitySchemes: $ref: definitions/security.yaml + parameters: + roomId: + in: path + name: roomId + description: The ID of the room containing the parent event. + required: true + example: "!636q39766251:matrix.org" + schema: + type: string + eventId: + in: path + name: eventId + description: The ID of the parent event whose child events are to be returned. + required: true + example: $asfDuShaf7Gafaw + schema: + type: string + from: + in: query + name: from + description: |- + The pagination token to start returning results from. If not supplied, results + start at the most recent topological event known to the server. + + Can be a `next_batch` or `prev_batch` token from a previous call, or a returned + `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages), + or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). + required: false + example: page2_token + schema: + type: string + to: + in: query + 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 + example: page3_token + schema: + type: string + limit: + in: query + 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 + example: 20 + schema: + type: integer + dir: + in: query + name: dir + x-addedInMatrixVersion: "1.4" + description: |- + Optional (default `b`) 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`. + schema: + type: string + enum: + - b + - f + relType: + in: path + name: relType + description: The [relationship type](/client-server-api/#relationship-types) to + search for. + required: true + example: org.example.my_relation + schema: + type: string + schemas: + response: + type: object + properties: + 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 this is the start of the result set, i.e. this is the first batch/page. + responses: + "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). + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "Event not found." + } + examples: + response: + value: { + "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" + }