From 5bb8b3ecd80a2c6ad0e5988e5ceb80f31921a4bd Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 8 Jun 2022 14:51:57 -0600 Subject: [PATCH] Apply suggestions on all 3 endpoints --- data/api/client-server/relations.yaml | 82 ++++++++++++++------------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index 05f49d28..dc0d8761 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -33,12 +33,13 @@ paths: description: |- 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 - supplied. This means it's only possible to paginate "forwards" through events. - An example of an *invalid* call would be a `from` token from page 2 of the results, - 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 - paginate forwards over the same range, however. + Note that when paginating the `from` token should be "after" the `to` token in + terms of topological ordering, because it is only possible to paginate "backwards" + through events, starting at `from`. + + For example, passing a `from` token from page 2 of the results, and a `to` token + 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 security: - accessToken: [] @@ -60,11 +61,11 @@ paths: name: from description: |- 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 - `start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) - or `next_batch`/`prev_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). + Can be a `next_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 x-example: "page2_token" - in: query @@ -119,8 +120,7 @@ paths: title: "ChildEventsChunk" type: array description: |- - The child events of the requested event. If a `relType` or `eventType` was - supplied on the URL, the events returned will match those details. + The child events of the requested event, ordered topologically most-recent first. items: allOf: - "$ref": "definitions/client_event.yaml" @@ -133,7 +133,7 @@ paths: type: string description: |- 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'] 404: description: |- @@ -156,12 +156,13 @@ paths: Retrieve all of the child events for a given parent event which relate to the parent using the given `relType`. - Note that when paginating the `from` token must be *before* the `to` token, if - supplied. This means it's only possible to paginate "forwards" through events. - An example of an *invalid* call would be a `from` token from page 2 of the results, - 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 - paginate forwards over the same range, however. + Note that when paginating the `from` token should be "after" the `to` token in + terms of topological ordering, because it is only possible to paginate "backwards" + through events, starting at `from`. + + For example, passing a `from` token from page 2 of the results, and a `to` token + 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 security: - accessToken: [] @@ -190,11 +191,11 @@ paths: name: from description: |- 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 - `start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) - or `next_batch`/`prev_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). + Can be a `next_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 x-example: "page2_token" - in: query @@ -249,8 +250,9 @@ paths: title: "ChildEventsChunk" type: array description: |- - The child events of the requested event. If a `relType` or `eventType` was - supplied on the URL, the events returned will match those details. + 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" @@ -263,7 +265,7 @@ paths: type: string description: |- 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'] 404: description: |- @@ -286,12 +288,13 @@ paths: 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`. - Note that when paginating the `from` token must be *before* the `to` token, if - supplied. This means it's only possible to paginate "forwards" through events. - An example of an *invalid* call would be a `from` token from page 2 of the results, - 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 - paginate forwards over the same range, however. + Note that when paginating the `from` token should be "after" the `to` token in + terms of topological ordering, because it is only possible to paginate "backwards" + through events, starting at `from`. + + For example, passing a `from` token from page 2 of the results, and a `to` token + 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 security: - accessToken: [] @@ -330,11 +333,11 @@ paths: name: from description: |- 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 - `start`/`end` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages) - or `next_batch`/`prev_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync). + Can be a `next_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 x-example: "page2_token" - in: query @@ -389,8 +392,9 @@ paths: title: "ChildEventsChunk" type: array description: |- - The child events of the requested event. If a `relType` or `eventType` was - supplied on the URL, the events returned will match those details. + 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" @@ -403,7 +407,7 @@ paths: type: string description: |- 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'] 404: description: |-