Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-03-26 13:04:10 +01:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Apply suggestions on all 3 endpoints

Browse source
This commit is contained in:
Travis Ralston 2022-06-08 14:51:57 -06:00
parent c02e1f1af9
commit 5bb8b3ecd8
1 changed files with 43 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -33,12 +33,13 @@ paths:
description: |- description: |-
Retrieve all of the child events for a given parent event. Retrieve all of the child events for a given parent event.
Note that when paginating the `from` token must be *before* the `to` token, if Note that when paginating the `from` token should be "after" the `to` token in
supplied. This means it's only possible to paginate "forwards" through events. terms of topological ordering, because it is only possible to paginate "backwards"
An example of an *invalid* call would be a `from` token from page 2 of the results, through events, starting at `from`.
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 For example, passing a `from` token from page 2 of the results, and a `to` token
paginate forwards over the same range, however. from page 1, would return the empty set. The caller can use a `from` token from
page 1 and a `to` token from page 2 to paginate over the same range, however.
operationId: getRelatingEvents operationId: getRelatingEvents
security: security:
- accessToken: [] - accessToken: []
@ -60,11 +61,11 @@ paths:
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 earliest 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` token from a previous call, or a returned
`start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or `next_batch`/`prev_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
x-example: "page2_token" x-example: "page2_token"
- in: query - in: query
@ -119,8 +120,7 @@ paths:
title: "ChildEventsChunk" title: "ChildEventsChunk"
type: array type: array
description: |- description: |-
The child events of the requested event. If a `relType` or `eventType` was The child events of the requested event, ordered topologically most-recent first.
supplied on the URL, the events returned will match those details.
items: items:
allOf: allOf:
- "$ref": "definitions/client_event.yaml" - "$ref": "definitions/client_event.yaml"
@ -133,7 +133,7 @@ paths:
type: string type: string
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 there are no prior results to fetch, 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: ['chunk'] required: ['chunk']
404: 404:
description: |- description: |-
@ -156,12 +156,13 @@ paths:
Retrieve all of the child events for a given parent event which relate to the parent Retrieve all of the child events for a given parent event which relate to the parent
using the given `relType`. using the given `relType`.
Note that when paginating the `from` token must be *before* the `to` token, if Note that when paginating the `from` token should be "after" the `to` token in
supplied. This means it's only possible to paginate "forwards" through events. terms of topological ordering, because it is only possible to paginate "backwards"
An example of an *invalid* call would be a `from` token from page 2 of the results, through events, starting at `from`.
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 For example, passing a `from` token from page 2 of the results, and a `to` token
paginate forwards over the same range, however. from page 1, would return the empty set. The caller can use a `from` token from
page 1 and a `to` token from page 2 to paginate over the same range, however.
operationId: getRelatingEventsWithRelType operationId: getRelatingEventsWithRelType
security: security:
- accessToken: [] - accessToken: []
@ -190,11 +191,11 @@ paths:
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 earliest 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` token from a previous call, or a returned
`start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or `next_batch`/`prev_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
x-example: "page2_token" x-example: "page2_token"
- in: query - in: query
@ -249,8 +250,9 @@ paths:
title: "ChildEventsChunk" title: "ChildEventsChunk"
type: array type: array
description: |- description: |-
The child events of the requested event. If a `relType` or `eventType` was The child events of the requested event, ordered topologically
supplied on the URL, the events returned will match those details. most-recent first. The events returned will match the `relType`
supplied in the URL.
items: items:
allOf: allOf:
- "$ref": "definitions/client_event.yaml" - "$ref": "definitions/client_event.yaml"
@ -263,7 +265,7 @@ paths:
type: string type: string
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 there are no prior results to fetch, 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: ['chunk'] required: ['chunk']
404: 404:
description: |- description: |-
@ -286,12 +288,13 @@ paths:
Retrieve all of the child events for a given parent event which relate to the parent 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`. using the given `relType` and have the given `eventType`.
Note that when paginating the `from` token must be *before* the `to` token, if Note that when paginating the `from` token should be "after" the `to` token in
supplied. This means it's only possible to paginate "forwards" through events. terms of topological ordering, because it is only possible to paginate "backwards"
An example of an *invalid* call would be a `from` token from page 2 of the results, through events, starting at `from`.
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 For example, passing a `from` token from page 2 of the results, and a `to` token
paginate forwards over the same range, however. from page 1, would return the empty set. The caller can use a `from` token from
page 1 and a `to` token from page 2 to paginate over the same range, however.
operationId: getRelatingEventsWithRelTypeAndEventType operationId: getRelatingEventsWithRelTypeAndEventType
security: security:
- accessToken: [] - accessToken: []
@ -330,11 +333,11 @@ paths:
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 earliest 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` token from a previous call, or a returned
`start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
or `next_batch`/`prev_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
x-example: "page2_token" x-example: "page2_token"
- in: query - in: query
@ -389,8 +392,9 @@ paths:
title: "ChildEventsChunk" title: "ChildEventsChunk"
type: array type: array
description: |- description: |-
The child events of the requested event. If a `relType` or `eventType` was The child events of the requested event, ordered topologically most-recent
supplied on the URL, the events returned will match those details. first. The events returned will match the `relType` and `eventType` supplied
in the URL.
items: items:
allOf: allOf:
- "$ref": "definitions/client_event.yaml" - "$ref": "definitions/client_event.yaml"
@ -403,7 +407,7 @@ paths:
type: string type: string
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 there are no prior results to fetch, 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: ['chunk'] required: ['chunk']
404: 404:
description: |- description: |-