Matrix-Mirrors/forked-synapse
1
0
Fork 0
mirror of https://mau.dev/maunium/synapse.git synced 2024-10-01 01:36:05 -04:00
Code Issues Packages Projects Releases Wiki Activity

Simplify structure of room admin API docs (#10313)

Browse Source
This commit is contained in:
Dirk Klimpel 2021-07-07 13:18:36 +02:00 committed by GitHub
parent bc60f999e8
commit 2d044667cf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 25 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
changelog.d/10313.doc Normal file
View File

@ -0,0 +1 @@
Simplify structure of room admin API.

69
docs/admin_api/rooms.md
View File

@ -1,13 +1,9 @@
# Contents # Contents
- [List Room API](#list-room-api) - [List Room API](#list-room-api)
* [Parameters](#parameters)
* [Usage](#usage)
- [Room Details API](#room-details-api) - [Room Details API](#room-details-api)
- [Room Members API](#room-members-api) - [Room Members API](#room-members-api)
- [Room State API](#room-state-api) - [Room State API](#room-state-api)
- [Delete Room API](#delete-room-api) - [Delete Room API](#delete-room-api)
* [Parameters](#parameters-1)
* [Response](#response)
* [Undoing room shutdowns](#undoing-room-shutdowns) * [Undoing room shutdowns](#undoing-room-shutdowns)
- [Make Room Admin API](#make-room-admin-api) - [Make Room Admin API](#make-room-admin-api)
- [Forward Extremities Admin API](#forward-extremities-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 server. There are various parameters available that allow for filtering and
sorting the returned list. This API supports pagination. sorting the returned list. This API supports pagination.
## Parameters **Parameters**
The following query parameters are available: 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 * `search_term` - Filter rooms by their room name. Search term can be contained in any
part of the room name. Defaults to no filtering. part of the room name. Defaults to no filtering.
**Response**
The following fields are possible in the JSON response body: The following fields are possible in the JSON response body:
* `rooms` - An array of objects, each containing information about a room. * `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 Use `prev_batch` for the `from` value in the next request to
get the "previous page" of results. get the "previous page" of results.
## Usage The API is:
A standard request with no filtering: A standard request with no filtering:
``` ```
GET /_synapse/admin/v1/rooms GET /_synapse/admin/v1/rooms
{}
``` ```
Response: A response body like the following is returned:
```jsonc ```jsonc
{ {
@ -137,11 +133,9 @@ Filtering by room name:
``` ```
GET /_synapse/admin/v1/rooms?search_term=TWIM GET /_synapse/admin/v1/rooms?search_term=TWIM
{}
``` ```
Response: A response body like the following is returned:
```json ```json
{ {
@ -172,11 +166,9 @@ Paginating through a list of rooms:
``` ```
GET /_synapse/admin/v1/rooms?order_by=size GET /_synapse/admin/v1/rooms?order_by=size
{}
``` ```
Response: A response body like the following is returned:
```jsonc ```jsonc
{ {
@ -228,11 +220,9 @@ parameter to the value of `next_token`.
``` ```
GET /_synapse/admin/v1/rooms?order_by=size&from=100 GET /_synapse/admin/v1/rooms?order_by=size&from=100
{}
``` ```
Response: A response body like the following is returned:
```jsonc ```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"]. * `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. * `state_events` - Total number of state_events of a room. Complexity of the room.
## Usage The API is:
A standard request:
``` ```
GET /_synapse/admin/v1/rooms/<room_id> GET /_synapse/admin/v1/rooms/<room_id>
{}
``` ```
Response: A response body like the following is returned:
```json ```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. * `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. * `total` - Total number of members in the room.
## Usage The API is:
A standard request:
``` ```
GET /_synapse/admin/v1/rooms/<room_id>/members GET /_synapse/admin/v1/rooms/<room_id>/members
{}
``` ```
Response: A response body like the following is returned:
```json ```json
{ {
@ -378,17 +360,13 @@ The response includes the following fields:
* `state` - The current state of the room at the time of request. * `state` - The current state of the room at the time of request.
## Usage The API is:
A standard request:
``` ```
GET /_synapse/admin/v1/rooms/<room_id>/state GET /_synapse/admin/v1/rooms/<room_id>/state
{}
``` ```
Response: A response body like the following is returned:
```json ```json
{ {
@ -432,6 +410,7 @@ DELETE /_synapse/admin/v1/rooms/<room_id>
``` ```
with a body of: with a body of:
```json ```json
{ {
"new_room_user_id": "@someuser:example.com", "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: 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 `{}`. 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: 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.: optionally be specified, e.g.:
``` ```
POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin POST /_synapse/admin/v1/rooms/<room_id_or_alias>/make_room_admin
{ {
"user_id": "@foo:example.com" "user_id": "@foo:example.com"
} }
``` ```
# Forward Extremities Admin API # 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: 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: A response as follows will be returned:
@ -581,7 +560,7 @@ A response as follows will be returned:
"received_ts": 1611263016761 "received_ts": 1611263016761
} }
] ]
} }
``` ```
## Deleting forward extremities ## Deleting forward extremities
@ -594,7 +573,7 @@ If a room has lots of forward extremities, the extra can be
deleted as follows: 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 A response as follows will be returned, indicating the amount of forward extremities