archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Factor out all the common parameters of the various /relations apis (#1745)

Browse Source 
Contributed by @zecakeh bd54781052.

Co-authored-by: Richard van der Hoff <richard@matrix.org>
pull/1754/head
David Baker 8 months ago committed by GitHub
parent 38796de79a
commit bb4003afa8
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 196 additions and 362 deletions
Show Stats Download Patch File Download Diff File

1
changelogs/internal/newsfragments/1745.clarification
Unescape Escape View File

@ -0,0 +1 @@
Factor out all the common parameters of the various `/relations` apis.

423
data/api/client-server/relations.yaml
Unescape Escape View File

@ -33,69 +33,12 @@ 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/from'
required: true - $ref: '#/components/parameters/to'
example: "!636q39766251:matrix.org" - $ref: '#/components/parameters/limit'
schema: - $ref: '#/components/parameters/dir'
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
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.
@ -107,7 +50,9 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object allOf:
- $ref: '#/components/schemas/response'
- type: object
properties: properties:
chunk: chunk:
title: ChildEventsChunk title: ChildEventsChunk
@ -115,52 +60,14 @@ paths:
description: The child events of the requested event, ordered topologically description: The child events of the requested event, ordered topologically
most-recent first. most-recent first.
items: items:
allOf: $ref: definitions/client_event.yaml
- $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: required:
- chunk - 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}`
@ -182,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.
@ -264,7 +107,9 @@ paths:
content: content:
application/json: application/json:
schema: schema:
type: object allOf:
- $ref: '#/components/schemas/response'
- type: object
properties: properties:
chunk: chunk:
title: ChildEventsChunk title: ChildEventsChunk
@ -274,52 +119,14 @@ paths:
most-recent first. The events returned will match the `relType` most-recent first. The events returned will match the `relType`
supplied in the URL. supplied in the URL.
items: items:
allOf: $ref: definitions/client_event.yaml
- $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: required:
- chunk - 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}`
@ -342,40 +149,91 @@ paths:
security: security:
- accessToken: [] - accessToken: []
parameters: parameters:
- $ref: '#/components/parameters/roomId'
- $ref: '#/components/parameters/eventId'
- $ref: '#/components/parameters/relType'
- in: path - in: path
name: eventType
description: |-
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
example: m.room.message
schema:
type: string
- $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.
"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.
content:
application/json:
schema:
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:
$ref: '#/components/examples/response'
"404":
$ref: '#/components/responses/404'
tags:
- Event relationships
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml
parameters:
roomId:
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
- in: path eventId:
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
- in: path from:
name: relType in: query
description: The [relationship type](/client-server-api/#relationship-types) to
search for.
required: true
example: org.example.my_relation
schema:
type: string
- in: path
name: eventType
description: |-
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
example: m.room.message
schema:
type: string
- 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
@ -388,7 +246,8 @@ paths:
example: page2_token example: page2_token
schema: schema:
type: string type: string
- in: query to:
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
@ -400,7 +259,8 @@ paths:
example: page3_token example: page3_token
schema: schema:
type: string type: string
- in: query limit:
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
@ -411,7 +271,8 @@ paths:
example: 20 example: 20
schema: schema:
type: integer type: integer
- in: query dir:
in: query
name: dir name: dir
x-addedInMatrixVersion: "1.4" x-addedInMatrixVersion: "1.4"
description: |- description: |-
@ -424,29 +285,19 @@ paths:
enum: enum:
- b - b
- f - f
responses: relType:
# note: this endpoint deliberately does not support rate limiting, therefore a in: path
# 429 error response is not included. name: relType
"200": description: The [relationship type](/client-server-api/#relationship-types) to
description: |- search for.
The paginated child events which point to the parent. If no events are required: true
pointing to the parent or the pagination yields no results, an empty `chunk` example: org.example.my_relation
is returned.
content:
application/json:
schema: schema:
type: string
schemas:
response:
type: object type: object
properties: 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: next_batch:
type: string type: string
description: |- description: |-
@ -457,8 +308,21 @@ paths:
description: |- description: |-
An opaque string representing a pagination token. The absence of this token 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. means this is the start of the result set, i.e. this is the first batch/page.
required: responses:
- 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).
content:
application/json:
schema:
$ref: definitions/errors/error.yaml
examples:
response:
value: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
examples: examples:
response: response:
value: { value: {
@ -477,34 +341,3 @@ paths:
"next_batch": "page2_token", "next_batch": "page2_token",
"prev_batch": "page1_token" "prev_batch": "page1_token"
} }
"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."
}
tags:
- Event relationships
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client/v1
components:
securitySchemes:
$ref: definitions/security.yaml

Write Preview
Loading…
Cancel
Save