Factor out all the common parameters of the various /relations apis (#1745)
Contributed by @zecakeh bd54781052.
Co-authored-by: Richard van der Hoff <richard@matrix.org>
This commit is contained in:
David Baker
GitHub
parent
38796de79a
commit
bb4003afa8
2 changed files with 196 additions and 362 deletions
1
changelogs/internal/newsfragments/1745.clarification
Normal file
1
changelogs/internal/newsfragments/1745.clarification
Normal file
|
|
@ -0,0 +1 @@
|
|||
Factor out all the common parameters of the various `/relations` apis.
|
||||
|
|
@ -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"
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue