diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index d0f0e91f..44bd4151 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -2057,6 +2057,7 @@ The endpoints where the server *should* include bundled aggregations are: * [`GET /sync`](#get_matrixclientv3sync) when the relevant section has a `limited` value of `true`. * [`POST /search`](#post_matrixclientv3search) for any matching events under `room_events`. +* {{< added-in v="1.4" >}} [`GET /rooms/{roomId}/threads`](#get_matrixclientv1roomsroomidthreads) {{% boxes/note %}} The server is **not** required to return bundled aggregations on deprecated endpoints diff --git a/content/client-server-api/modules/threading.md b/content/client-server-api/modules/threading.md index 7262af03..599354dd 100644 --- a/content/client-server-api/modules/threading.md +++ b/content/client-server-api/modules/threading.md @@ -192,16 +192,10 @@ It does not include events sent by [ignored users](#ignoring-users). 1. The `sender` of the event receiving the bundle (they sent the thread root). 2. The `sender` of an event which references the thread root with a `rel_type` of `m.thread`. -#### Client behaviour +#### Querying threads in a room -Client-specific behaviours are described throughout this module and are not repeated here. +Clients looking to get all the events in a thread can use +[`GET /relations/{threadRootId}/m.thread`](#get_matrixclientv1roomsroomidrelationseventidreltype), +however getting all threads in a room is done through a dedicated API: -Clients might wish to read up on the following endpoints to achieve thread-specific functionality, -however: -* [`GET /relations`](#get_matrixclientv1roomsroomidrelationseventidreltype) using the thread root - ID to retrieve all events in a thread. -* ***DEVNOTE***: Normally we'd talk about `related_by_rel_types` and `related_by_senders` filters here, - but because MSC3856 literally replaces them we just don't bother speccing them at this point. At the - time you're reading this, the commit is targeting MSC3440 specifically and doesn't want to bleed too - much into the other MSCs, for reasons of clarity. Then again, here I am leaving a long comment explaining - why we aren't including a relatively short MSC in this commit. You're welcome. +{{% http-api spec="client-server" api="threads_list" %}} diff --git a/data/api/client-server/threads_list.yaml b/data/api/client-server/threads_list.yaml new file mode 100644 index 00000000..c0c9cbd0 --- /dev/null +++ b/data/api/client-server/threads_list.yaml @@ -0,0 +1,135 @@ +# Copyright 2022 The Matrix.org Foundation C.I.C. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +swagger: '2.0' +info: + title: "Matrix Client-Server Threads List API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/v1 +consumes: + - application/json +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/rooms/{roomId}/threads": + get: + x-addedInMatrixVersion: "1.4" + summary: Retrieve a list of threads in a room, with optional filters. + description: |- + Paginates over the thread roots in a room, ordered by the `latest_event` of each thread root + in its bundle. + operationId: getThreadRoots + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room ID where the thread roots are located. + required: true + x-example: "!room:example.org" + - in: query + type: string + name: include + enum: [all, participated] + description: |- + Optional (default `all`) flag to denote which thread roots are of interest to the caller. + When `all`, all thread roots found in the room are returned. When `participated`, only + thread roots for threads the user has [participated in](/client-server-api/#server-side-aggreagtion-of-mthread-relationships) + will be returned. + x-example: "all" + - in: query + type: integer + name: limit + description: |- + Optional limit for the maximum number of thread roots to include per response. Must be an integer + greater than zero. + + Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. + x-example: 20 + - in: query + type: string + name: from + description: |- + A pagination token from a previous result. When not provided, the server starts paginating from + the most recent event visible to the user (as per history visibility rules; topologically). + x-example: "next_batch_token" + responses: + 200: + description: |- + A portion of the available thread roots in the room, based on the filter criteria. + examples: + application/json: { + "chunk": [{ "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" }], + "next_batch": "next_batch_token" + } + schema: + type: object + properties: + chunk: + type: array + description: |- + The thread roots, ordered by the `latest_event` in each event's aggregation bundle. All events + returned include bundled [aggregations](/client-server-api/#aggregations). + + If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the + event is returned redacted to the caller. This is to simulate the same behaviour of a client doing + aggregation locally on the thread. + items: + $ref: "definitions/client_event.yaml" + next_batch: + type: string + description: |- + A token to supply to `from` to keep paginating the responses. Not present when there are + no further results. + required: [chunk] + 403: + description: |- + The user cannot view or peek on the room. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: + + - The room is not set up for peeking. + - The user has been banned from the room. + - The room does not exist. + examples: + application/json: { + "errcode": "M_FORBIDDEN", + "error": "You are not allowed to view this room." + } + schema: + "$ref": "definitions/errors/error.yaml" + 400: + description: |- + The request was invalid in some way. A meaningful `errcode` + and description error text will be returned. Example reasons for rejection are: + + - The `from` token is unknown to the server. + examples: + application/json: { + "errcode": "M_INVALID_PARAM", + "error": "Unknown pagination token" + } + schema: + "$ref": "definitions/errors/error.yaml" + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Threads