Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-19 01:24:09 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Factor out more commnon parts

Browse source 
Contributed by @zecakeh bd54781052.
This commit is contained in:
Richard van der Hoff 2024-03-19 15:16:58 +00:00
parent 074ebb4ac5
commit 8c211939c6
1 changed files with 178 additions and 358 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -50,60 +50,24 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object allOf:
properties: - $ref: '#/components/schemas/response'
chunk: - type: object
title: ChildEventsChunk properties:
type: array chunk:
description: The child events of the requested event, ordered topologically title: ChildEventsChunk
most-recent first. type: array
items: description: The child events of the requested event, ordered topologically
allOf: most-recent first.
- $ref: definitions/client_event.yaml items:
next_batch: $ref: definitions/client_event.yaml
type: string required:
description: |- - chunk
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
examples: examples:
response: response:
value: { $ref: '#/components/examples/response'
"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"
}
"404": "404":
description: |- $ref: '#/components/responses/404'
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."
}
tags: tags:
- Event relationships - Event relationships
# The same as above, with added `/{relType}` # The same as above, with added `/{relType}`
@ -125,77 +89,13 @@ paths:
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - $ref: '#/components/parameters/roomId'
name: roomId - $ref: '#/components/parameters/eventId'
description: The ID of the room containing the parent event. - $ref: '#/components/parameters/relType'
required: true - $ref: '#/components/parameters/from'
example: "!636q39766251:matrix.org" - $ref: '#/components/parameters/to'
schema: - $ref: '#/components/parameters/limit'
type: string - $ref: '#/components/parameters/dir'
- 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
responses: responses:
# note: this endpoint deliberately does not support rate limiting, therefore a # note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included. # 429 error response is not included.
@ -207,62 +107,26 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object allOf:
properties: - $ref: '#/components/schemas/response'
chunk: - type: object
title: ChildEventsChunk properties:
type: array chunk:
description: |- title: ChildEventsChunk
The child events of the requested event, ordered topologically type: array
most-recent first. The events returned will match the `relType` description: |-
supplied in the URL. The child events of the requested event, ordered topologically
items: most-recent first. The events returned will match the `relType`
allOf: supplied in the URL.
- $ref: definitions/client_event.yaml items:
next_batch: $ref: definitions/client_event.yaml
type: string required:
description: |- - chunk
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
examples: examples:
response: response:
value: { $ref: '#/components/examples/response'
"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"
}
"404": "404":
description: |- $ref: '#/components/responses/404'
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."
}
tags: tags:
- Event relationships - Event relationships
# The same as above, with added `/{eventType}` # The same as above, with added `/{eventType}`
@ -285,28 +149,9 @@ paths:
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- in: path - $ref: '#/components/parameters/roomId'
name: roomId - $ref: '#/components/parameters/eventId'
description: The ID of the room containing the parent event. - $ref: '#/components/parameters/relType'
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: path - in: path
name: eventType name: eventType
description: |- description: |-
@ -318,55 +163,10 @@ paths:
example: m.room.message example: m.room.message
schema: schema:
type: string type: string
- in: query - $ref: '#/components/parameters/from'
name: from - $ref: '#/components/parameters/to'
description: |- - $ref: '#/components/parameters/limit'
The pagination token to start returning results from. If not supplied, results - $ref: '#/components/parameters/dir'
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
responses: responses:
# note: this endpoint deliberately does not support rate limiting, therefore a # note: this endpoint deliberately does not support rate limiting, therefore a
# 429 error response is not included. # 429 error response is not included.
@ -378,62 +178,26 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object allOf:
properties: - $ref: '#/components/schemas/response'
chunk: - type: object
title: ChildEventsChunk properties:
type: array chunk:
description: |- title: ChildEventsChunk
The child events of the requested event, ordered topologically most-recent type: array
first. The events returned will match the `relType` and `eventType` supplied description: |-
in the URL. The child events of the requested event, ordered topologically most-recent
items: first. The events returned will match the `relType` and `eventType` supplied
allOf: in the URL.
- $ref: definitions/client_event.yaml items:
next_batch: $ref: definitions/client_event.yaml
type: string required:
description: |- - chunk
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
examples: examples:
response: response:
value: { $ref: '#/components/examples/response'
"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"
}
"404": "404":
description: |- $ref: '#/components/responses/404'
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."
}
tags: tags:
- Event relationships - Event relationships
servers: servers:
@ -453,71 +217,127 @@ components:
$ref: definitions/security.yaml $ref: definitions/security.yaml
parameters: parameters:
roomId: roomId:
in: path in: path
name: roomId name: roomId
description: The ID of the room containing the parent event. description: The ID of the room containing the parent event.
required: true required: true
example: "!636q39766251:matrix.org" example: "!636q39766251:matrix.org"
schema: schema:
type: string type: string
eventId: eventId:
in: path in: path
name: eventId name: eventId
description: The ID of the parent event whose child events are to be returned. description: The ID of the parent event whose child events are to be returned.
required: true required: true
example: $asfDuShaf7Gafaw example: $asfDuShaf7Gafaw
schema: schema:
type: string type: string
from: from:
in: query in: query
name: from name: from
description: |- description: |-
The pagination token to start returning results from. If not supplied, results The pagination token to start returning results from. If not supplied, results
start at the most recent topological event known to the server. 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 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), `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
required: false required: false
example: page2_token example: page2_token
schema: schema:
type: string type: string
to: to:
in: query in: query
name: to name: to
description: |- description: |-
The pagination token to stop returning results at. If not supplied, results The pagination token to stop returning results at. If not supplied, results
continue up to `limit` or until there are no more events. 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 Like `from`, this can be a previous token from a prior call to this endpoint
or from `/messages` or `/sync`. or from `/messages` or `/sync`.
required: false required: false
example: page3_token example: page3_token
schema: schema:
type: string type: string
limit: limit:
in: query in: query
name: limit name: limit
description: |- description: |-
The maximum number of results to return in a single `chunk`. The server can 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. and should apply a maximum value to this parameter to avoid large responses.
Similarly, the server should apply a default value when not supplied. Similarly, the server should apply a default value when not supplied.
required: false required: false
example: 20 example: 20
schema: schema:
type: integer type: integer
dir: dir:
in: query in: query
name: dir name: dir
x-addedInMatrixVersion: "1.4" x-addedInMatrixVersion: "1.4"
description: |- description: |-
Optional (default `b`) direction to return events from. If this is set to `f`, events 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 will be returned in chronological order starting at `from`. If it
is set to `b`, events will be returned in *reverse* chronological is set to `b`, events will be returned in *reverse* chronological
order, again starting at `from`. order, again starting at `from`.
schema: 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 type: string
enum: description: |-
- b An opaque string representing a pagination token. The absence of this token
- f 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"
}