mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-27 11:28:38 +01:00
820704a16a
According the the openapi spec, examples for responses and schemas should be raw objects rather than being json strings. (It's unclear what non-json examples should look like...). The swagger UI used to support json strings, but no longer does. In short, let's turn the json strings into their raw formats.
300 lines
11 KiB
YAML
300 lines
11 KiB
YAML
# Copyright 2016 OpenMarket Ltd
|
|
#
|
|
# 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 Room Creation API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
- http
|
|
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
paths:
|
|
"/publicRooms":
|
|
get:
|
|
summary: Lists the public rooms on the server.
|
|
description: |-
|
|
Lists the public rooms on the server.
|
|
|
|
This API returns paginated responses. The rooms are ordered by the number
|
|
of joined members, with the largest rooms first.
|
|
parameters:
|
|
- in: query
|
|
name: limit
|
|
type: number
|
|
description: |-
|
|
Limit the number of results returned.
|
|
- in: query
|
|
name: since
|
|
type: string
|
|
description: |-
|
|
A pagination token from a previous request, allowing clients to
|
|
get the next (or previous) batch of rooms.
|
|
The direction of pagination is specified solely by which token
|
|
is supplied, rather than via an explicit flag.
|
|
- in: query
|
|
name: server
|
|
type: string
|
|
description: |-
|
|
The server to fetch the public room lists from. Defaults to the
|
|
local server.
|
|
responses:
|
|
200:
|
|
description: A list of the rooms on the server.
|
|
schema:
|
|
type: object
|
|
description: A list of the rooms on the server.
|
|
required: ["chunk"]
|
|
properties:
|
|
chunk:
|
|
title: "PublicRoomsChunks"
|
|
type: array
|
|
description: |-
|
|
A paginated chunk of public rooms.
|
|
items:
|
|
type: object
|
|
title: "PublicRoomsChunk"
|
|
required:
|
|
- room_id
|
|
- num_joined_members
|
|
- world_readable
|
|
- guest_can_join
|
|
properties:
|
|
aliases:
|
|
type: array
|
|
description: |-
|
|
Aliases of the room. May be empty.
|
|
items:
|
|
type: string
|
|
canonical_alias:
|
|
type: string
|
|
description: |-
|
|
The canonical alias of the room, if any.
|
|
name:
|
|
type: string
|
|
description: |-
|
|
The name of the room, if any.
|
|
num_joined_members:
|
|
type: number
|
|
description: |-
|
|
The number of members joined to the room.
|
|
room_id:
|
|
type: string
|
|
description: |-
|
|
The ID of the room.
|
|
topic:
|
|
type: string
|
|
description: |-
|
|
The topic of the room, if any.
|
|
world_readable:
|
|
type: boolean
|
|
description: |-
|
|
Whether the room may be viewed by guest users without joining.
|
|
guest_can_join:
|
|
type: boolean
|
|
description: |-
|
|
Whether guest users may join the room and participate in it.
|
|
If they can, they will be subject to ordinary power level
|
|
rules like any other user.
|
|
avatar_url:
|
|
type: string
|
|
description: The URL for the room's avatar, if one is set.
|
|
next_batch:
|
|
type: string
|
|
description: |-
|
|
A pagination token for the response. The absence of this token
|
|
means there are no more results to fetch and the client should
|
|
stop paginating.
|
|
prev_batch:
|
|
type: string
|
|
description: |-
|
|
A pagination token that allows fetching previous results. The
|
|
absence of this token means there are no results before this
|
|
batch, i.e. this is the first batch.
|
|
total_room_count_estimate:
|
|
type: number
|
|
description: |-
|
|
An estimate on the total number of public rooms, if the
|
|
server has an estimate.
|
|
examples:
|
|
application/json: {
|
|
"chunk": [
|
|
{
|
|
"aliases": ["#murrays:cheese.bar"],
|
|
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
|
|
"guest_can_join": false,
|
|
"name": "CHEESE",
|
|
"num_joined_members": 37,
|
|
"room_id": "!ol19s:bleecker.street",
|
|
"topic": "Tasty tasty cheese",
|
|
"world_readable": true
|
|
}
|
|
],
|
|
"next_batch": "p190q",
|
|
"prev_batch": "p1902",
|
|
"total_room_count_estimate": 115
|
|
}
|
|
tags:
|
|
- Room discovery
|
|
post:
|
|
summary: Lists the public rooms on the server with optional filter.
|
|
description: |-
|
|
Lists the public rooms on the server, with optional filter.
|
|
|
|
This API returns paginated responses. The rooms are ordered by the number
|
|
of joined members, with the largest rooms first.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: query
|
|
name: server
|
|
type: string
|
|
description: |-
|
|
The server to fetch the public room lists from. Defaults to the
|
|
local server.
|
|
- in: body
|
|
name: body
|
|
required: true
|
|
description: |-
|
|
Options for which rooms to return.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
limit:
|
|
type: number
|
|
description: |-
|
|
Limit the number of results returned.
|
|
since:
|
|
type: string
|
|
description: |-
|
|
A pagination token from a previous request, allowing clients
|
|
to get the next (or previous) batch of rooms. The direction
|
|
of pagination is specified solely by which token is supplied,
|
|
rather than via an explicit flag.
|
|
filter:
|
|
type: object
|
|
title: "Filter"
|
|
description: |-
|
|
Filter to apply to the results.
|
|
properties:
|
|
generic_search_term:
|
|
type: string
|
|
description: |-
|
|
A string to search for in the room metadata, e.g. name,
|
|
topic, canonical alias etc. (Optional).
|
|
example: {
|
|
"limit": 10, "filter": {"generic_search_term": "foo"}}
|
|
responses:
|
|
200:
|
|
description: A list of the rooms on the server.
|
|
schema:
|
|
type: object
|
|
description: A list of the rooms on the server.
|
|
required: ["chunk"]
|
|
properties:
|
|
chunk:
|
|
title: "PublicRoomsChunks"
|
|
type: array
|
|
description: |-
|
|
A paginated chunk of public rooms.
|
|
items:
|
|
type: object
|
|
title: "PublicRoomsChunk"
|
|
required:
|
|
- room_id
|
|
- num_joined_members
|
|
- world_readable
|
|
- guest_can_join
|
|
properties:
|
|
aliases:
|
|
type: array
|
|
description: |-
|
|
Aliases of the room. May be empty.
|
|
items:
|
|
type: string
|
|
canonical_alias:
|
|
type: string
|
|
description: |-
|
|
The canonical alias of the room, if any.
|
|
name:
|
|
type: string
|
|
description: |-
|
|
The name of the room, if any.
|
|
num_joined_members:
|
|
type: number
|
|
description: |-
|
|
The number of members joined to the room.
|
|
room_id:
|
|
type: string
|
|
description: |-
|
|
The ID of the room.
|
|
topic:
|
|
type: string
|
|
description: |-
|
|
The topic of the room, if any.
|
|
world_readable:
|
|
type: boolean
|
|
description: |-
|
|
Whether the room may be viewed by guest users without joining.
|
|
guest_can_join:
|
|
type: boolean
|
|
description: |-
|
|
Whether guest users may join the room and participate in it.
|
|
If they can, they will be subject to ordinary power level
|
|
rules like any other user.
|
|
avatar_url:
|
|
type: string
|
|
description: The URL for the room's avatar, if one is set.
|
|
next_batch:
|
|
type: string
|
|
description: |-
|
|
A pagination token for the response. The absence of this token
|
|
means there are no more results to fetch and the client should
|
|
stop paginating.
|
|
prev_batch:
|
|
type: string
|
|
description: |-
|
|
A pagination token that allows fetching previous results. The
|
|
absence of this token means there are no results before this
|
|
batch, i.e. this is the first batch.
|
|
total_room_count_estimate:
|
|
type: number
|
|
description: |-
|
|
An estimate on the total number of public rooms, if the
|
|
server has an estimate.
|
|
examples:
|
|
application/json: {
|
|
"chunk": [
|
|
{
|
|
"aliases": ["#murrays:cheese.bar"],
|
|
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
|
|
"guest_can_join": false,
|
|
"name": "CHEESE",
|
|
"num_joined_members": 37,
|
|
"room_id": "!ol19s:bleecker.street",
|
|
"topic": "Tasty tasty cheese",
|
|
"world_readable": true
|
|
}
|
|
],
|
|
"next_batch": "p190q",
|
|
"prev_batch": "p1902",
|
|
"total_room_count_estimate": 115
|
|
}
|
|
tags:
|
|
- Room discovery
|