mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-26 13:04:10 +01:00
Spec MSC3856: Threads list API
This commit is contained in:
Travis Ralston
parent
646b787480
commit
26f603a615
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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" %}}
|
||||
|
|
|
|||
135
data/api/client-server/threads_list.yaml
Normal file
135
data/api/client-server/threads_list.yaml
Normal file
|
|
@ -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
|
||||
Loading…
Reference in a new issue