2370a4c970
Fixes https://matrix.org/jira/browse/SPEC-429. Synapse currently follows the specified ordering, but does *not* give the specified error when the state is invalid (instead it creates the room anyway but gives a 403 M_FORBIDDEN). Still, I don't think that should be a real problem for any real clients, and nothing would break if we changed this in synapse, so it might as well go in the spec anyway.
208 lines
8.2 KiB
YAML
208 lines
8.2 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
|
|
securityDefinitions:
|
|
$ref: definitions/security.yaml
|
|
paths:
|
|
"/createRoom":
|
|
post:
|
|
summary: Create a new room
|
|
description: |-
|
|
Create a new room with various configuration options.
|
|
|
|
The server MUST apply the normal state resolution rules when creating
|
|
the new room, including checking power levels for each event. It MUST
|
|
apply the events implied by the request in the following order:
|
|
|
|
1. Events set by ``presets``.
|
|
|
|
2. Events listed in ``initial_state``, in the order that they are
|
|
listed.
|
|
|
|
3. Events implied by ``name`` and ``topic``.
|
|
|
|
4. Invite events implied by ``invite`` and ``invite_3pid``.
|
|
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: body
|
|
name: body
|
|
description: The desired room configuration.
|
|
schema:
|
|
type: object
|
|
example: |-
|
|
{
|
|
"preset": "public_chat",
|
|
"room_alias_name": "thepub",
|
|
"name": "The Grand Duke Pub",
|
|
"topic": "All about happy hour",
|
|
"creation_content": {
|
|
"m.federate": false
|
|
}
|
|
}
|
|
properties:
|
|
visibility:
|
|
type: string
|
|
enum: ["public", "private"]
|
|
description: |-
|
|
A ``public`` visibility indicates that the room will be shown
|
|
in the published room list. A ``private`` visibility will hide
|
|
the room from the published room list. Rooms default to
|
|
``private`` visibility if this key is not included. NB: This
|
|
should not be confused with ``join_rules`` which also uses the
|
|
word ``public``.
|
|
room_alias_name:
|
|
type: string
|
|
description: |-
|
|
The desired room alias **local part**. If this is included, a
|
|
room alias will be created and mapped to the newly created
|
|
room. The alias will belong on the *same* homeserver which
|
|
created the room. For example, if this was set to "foo" and
|
|
sent to the homeserver "example.com" the complete room alias
|
|
would be ``#foo:example.com``.
|
|
name:
|
|
type: string
|
|
description: |-
|
|
If this is included, an ``m.room.name`` event will be sent
|
|
into the room to indicate the name of the room. See Room
|
|
Events for more information on ``m.room.name``.
|
|
topic:
|
|
type: string
|
|
description: |-
|
|
If this is included, an ``m.room.topic`` event will be sent
|
|
into the room to indicate the topic for the room. See Room
|
|
Events for more information on ``m.room.topic``.
|
|
invite:
|
|
type: array
|
|
description: |-
|
|
A list of user IDs to invite to the room. This will tell the
|
|
server to invite everyone in the list to the newly created room.
|
|
items:
|
|
type: string
|
|
invite_3pid:
|
|
type: array
|
|
description: |-
|
|
A list of objects representing third party IDs to invite into
|
|
the room.
|
|
items:
|
|
type: object
|
|
title: Invite3pid
|
|
properties:
|
|
id_server:
|
|
type: string
|
|
description: The hostname+port of the identity server which should be used for third party identifier lookups.
|
|
medium:
|
|
type: string
|
|
# TODO: Link to identity service spec when it eixsts
|
|
description: The kind of address being passed in the address field, for example ``email``.
|
|
address:
|
|
type: string
|
|
description: The invitee's third party identifier.
|
|
required: ["id_server", "medium", "address"]
|
|
creation_content:
|
|
title: CreationContent
|
|
type: object
|
|
description: |-
|
|
Extra keys to be added to the content of the ``m.room.create``.
|
|
The server will clobber the following keys: ``creator``. Future
|
|
versions of the specification may allow the server to clobber
|
|
other keys.
|
|
initial_state:
|
|
type: array
|
|
description: |-
|
|
A list of state events to set in the new room. This allows
|
|
the user to override the default state events set in the new
|
|
room. The expected format of the state events are an object
|
|
with type, state_key and content keys set.
|
|
|
|
Takes precedence over events set by ``presets``, but gets
|
|
overriden by ``name`` and ``topic`` keys.
|
|
items:
|
|
type: object
|
|
title: StateEvent
|
|
properties:
|
|
type:
|
|
type: string
|
|
state_key:
|
|
type: string
|
|
content:
|
|
type: string
|
|
preset:
|
|
type: string
|
|
enum: ["private_chat", "public_chat", "trusted_private_chat"]
|
|
description: |-
|
|
Convenience parameter for setting various default state events
|
|
based on a preset. Must be either:
|
|
|
|
``private_chat`` =>
|
|
``join_rules`` is set to ``invite``.
|
|
``history_visibility`` is set to ``shared``.
|
|
|
|
``trusted_private_chat`` =>
|
|
``join_rules`` is set to ``invite``.
|
|
``history_visibility`` is set to ``shared``.
|
|
All invitees are given the same power level as the room creator.
|
|
|
|
``public_chat``: =>
|
|
``join_rules`` is set to ``public``.
|
|
``history_visibility`` is set to ``shared``.
|
|
|
|
responses:
|
|
200:
|
|
description: Information about the newly created room.
|
|
schema:
|
|
type: object
|
|
description: Information about the newly created room.
|
|
properties:
|
|
room_id:
|
|
type: string
|
|
description: |-
|
|
The created room's ID.
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"room_id": "!sefiuhWgwghwWgh:example.com"
|
|
}
|
|
400:
|
|
description: |-
|
|
|
|
The request is invalid. A meaningful ``errcode`` and description
|
|
error text will be returned. Example reasons for rejection include:
|
|
|
|
- The request body is malformed (``errcode`` set to ``M_BAD_JSON``
|
|
or ``M_NOT_JSON``).
|
|
|
|
- The room alias specified is already taken (``errcode`` set to
|
|
``M_ROOM_IN_USE``).
|
|
|
|
- The initial state implied by the parameters to the request is
|
|
invalid: for example, the user's ``power_level`` is set below
|
|
that necessary to set the room name (``errcode`` set to
|
|
``M_INVALID_ROOM_STATE``).
|
|
|
|
tags:
|
|
- Room creation
|