forked from MirrorHub/synapse
Simplify structure of room admin API docs (#10313)
This commit is contained in:
Dirk Klimpel
GitHub
parent
bc60f999e8
commit
2d044667cf
2 changed files with 25 additions and 45 deletions
1
changelog.d/10313.doc
Normal file
1
changelog.d/10313.doc
Normal file
|
|
@ -0,0 +1 @@
|
|||
Simplify structure of room admin API.
|
||||
|
|
@ -1,13 +1,9 @@
|
|||
# Contents
|
||||
- [List Room API](#list-room-api)
|
||||
* [Parameters](#parameters)
|
||||
* [Usage](#usage)
|
||||
- [Room Details API](#room-details-api)
|
||||
- [Room Members API](#room-members-api)
|
||||
- [Room State API](#room-state-api)
|
||||
- [Delete Room API](#delete-room-api)
|
||||
* [Parameters](#parameters-1)
|
||||
* [Response](#response)
|
||||
* [Undoing room shutdowns](#undoing-room-shutdowns)
|
||||
- [Make Room Admin API](#make-room-admin-api)
|
||||
- [Forward Extremities Admin API](#forward-extremities-admin-api)
|
||||
|
|
@ -19,7 +15,7 @@ The List Room admin API allows server admins to get a list of rooms on their
|
|||
server. There are various parameters available that allow for filtering and
|
||||
sorting the returned list. This API supports pagination.
|
||||
|
||||
## Parameters
|
||||
**Parameters**
|
||||
|
||||
The following query parameters are available:
|
||||
|
||||
|
|
@ -46,6 +42,8 @@ The following query parameters are available:
|
|||
* `search_term` - Filter rooms by their room name. Search term can be contained in any
|
||||
part of the room name. Defaults to no filtering.
|
||||
|
||||
**Response**
|
||||
|
||||
The following fields are possible in the JSON response body:
|
||||
|
||||
* `rooms` - An array of objects, each containing information about a room.
|
||||
|
|
@ -79,17 +77,15 @@ The following fields are possible in the JSON response body:
|
|||
Use `prev_batch` for the `from` value in the next request to
|
||||
get the "previous page" of results.
|
||||
|
||||
## Usage
|
||||
The API is:
|
||||
|
||||
A standard request with no filtering:
|
||||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
|
|
@ -137,11 +133,9 @@ Filtering by room name:
|
|||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms?search_term=TWIM
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -172,11 +166,9 @@ Paginating through a list of rooms:
|
|||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms?order_by=size
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
|
|
@ -228,11 +220,9 @@ parameter to the value of `next_token`.
|
|||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms?order_by=size&from=100
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```jsonc
|
||||
{
|
||||
|
|
@ -304,17 +294,13 @@ The following fields are possible in the JSON response body:
|
|||
* `history_visibility` - Who can see the room history. One of: ["invited", "joined", "shared", "world_readable"].
|
||||
* `state_events` - Total number of state_events of a room. Complexity of the room.
|
||||
|
||||
## Usage
|
||||
|
||||
A standard request:
|
||||
The API is:
|
||||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms/<room_id>
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -347,17 +333,13 @@ The response includes the following fields:
|
|||
* `members` - A list of all the members that are present in the room, represented by their ids.
|
||||
* `total` - Total number of members in the room.
|
||||
|
||||
## Usage
|
||||
|
||||
A standard request:
|
||||
The API is:
|
||||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms/<room_id>/members
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -378,17 +360,13 @@ The response includes the following fields:
|
|||
|
||||
* `state` - The current state of the room at the time of request.
|
||||
|
||||
## Usage
|
||||
|
||||
A standard request:
|
||||
The API is:
|
||||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms/<room_id>/state
|
||||
|
||||
{}
|
||||
```
|
||||
|
||||
Response:
|
||||
A response body like the following is returned:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -432,6 +410,7 @@ DELETE /_synapse/admin/v1/rooms/<room_id>
|
|||
```
|
||||
|
||||
with a body of:
|
||||
|
||||
```json
|
||||
{
|
||||
"new_room_user_id": "@someuser:example.com",
|
||||
|
|
@ -461,7 +440,7 @@ A response body like the following is returned:
|
|||
}
|
||||
```
|
||||
|
||||
## Parameters
|
||||
**Parameters**
|
||||
|
||||
The following parameters should be set in the URL:
|
||||
|
||||
|
|
@ -491,7 +470,7 @@ The following JSON body parameters are available:
|
|||
|
||||
The JSON body must not be empty. The body must be at least `{}`.
|
||||
|
||||
## Response
|
||||
**Response**
|
||||
|
||||
The following fields are returned in the JSON response body:
|
||||
|
||||
|
|
@ -548,10 +527,10 @@ By default the server admin (the caller) is granted power, but another user can
|
|||
optionally be specified, e.g.:
|
||||
|
||||
```
|
||||
POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
|
||||
{
|
||||
"user_id": "@foo:example.com"
|
||||
}
|
||||
POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
|
||||
{
|
||||
"user_id": "@foo:example.com"
|
||||
}
|
||||
```
|
||||
|
||||
# Forward Extremities Admin API
|
||||
|
|
@ -565,7 +544,7 @@ extremities accumulate in a room, performance can become degraded. For details,
|
|||
To check the status of forward extremities for a room:
|
||||
|
||||
```
|
||||
GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
GET /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
```
|
||||
|
||||
A response as follows will be returned:
|
||||
|
|
@ -581,7 +560,7 @@ A response as follows will be returned:
|
|||
"received_ts": 1611263016761
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deleting forward extremities
|
||||
|
|
@ -594,7 +573,7 @@ If a room has lots of forward extremities, the extra can be
|
|||
deleted as follows:
|
||||
|
||||
```
|
||||
DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
DELETE /_synapse/admin/v1/rooms/<room_id_or_alias>/forward_extremities
|
||||
```
|
||||
|
||||
A response as follows will be returned, indicating the amount of forward extremities
|
||||
|
|
|
|||
Loading…
Reference in a new issue