wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into hs/dns-to-be-hostname

Browse source
This commit is contained in:
Will Hunt 2018-07-24 23:12:12 +01:00 • committed by GitHub
commit bdb881420c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
122 changed files with 2797 additions and 831 deletions
Download patch file Download diff file Expand all files Collapse all files

64
.circleci/config.yml Normal file
View file

@ -0,0 +1,64 @@
gendoc: &gendoc
name: Generate the docs
command: |
source /env/bin/activate
scripts/gendoc.py
genswagger: &genswagger
name: Generate the swagger
command: |
source /env/bin/activate
scripts/dump-swagger.py
buildswaggerui: &buildswaggerui
name: Build Swagger UI
command: |
ls scripts/
mkdir -p api/client-server
git clone https://github.com/matrix-org/swagger-ui swagger-ui
cp -r swagger-ui/dist/* api/client-server/
mkdir -p api/client-server/json
cp scripts/swagger/api-docs.json api/client-server/json/
wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/content/swagger.css -O api/client-server/swagger.css
wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch
patch api/client-server/index.html swagger-ui.patch
version: 2
jobs:
build-docs:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *gendoc
- store_artifacts:
path: scripts/gen
- run:
name: "Doc build is available at:"
command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL
build-swagger:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *genswagger
- run: *buildswaggerui
- store_artifacts:
path: api/client-server/
- run:
name: "Swagger UI is available at:"
command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL
workflows:
version: 2
build-spec:
jobs:
- build-docs
- build-swagger
notify:
webhooks:
- url: https://giles.cadair.com/circleci

3
.gitignore vendored
View file

@ -1,7 +1,7 @@
/api/node_modules
/assets
/assets.tar.gz
/env
/env*
/scripts/gen
/scripts/continuserv/continuserv
/scripts/speculator/speculator
@ -10,3 +10,4 @@
/templating/out
*.pyc
*.swp
_rendered.rst

8
.travis.yml
View file

@ -2,15 +2,15 @@ language: go
go:
- 1.8
sudo: false
sudo: required
# we only need a single git commit
git:
depth: 1
# test-and-build does the installation, so tell travis to skip the
# installation step
install: true
install:
- sudo apt-get update
- sudo apt-get install python3 python3-dev
script:
- ./scripts/test-and-build.sh

35
CONTRIBUTING.rst
View file

@ -69,6 +69,41 @@ For such changes, please do just open a `pull request`_.
.. _pull request: https://help.github.com/articles/about-pull-requests
Adding to the changelog
~~~~~~~~~~~~~~~~~~~~~~~
Currently only changes to the client-server API need to end up in a changelog. The
other APIs are not yet stable and therefore do not have a changelog. Adding to the
changelog can only be done after you've opened your pull request, so be sure to do
that first.
The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
form of "news fragments". The news fragments for the client-server API are stored
under ``changelogs/client_server/newsfragments``.
To create a changelog entry, create a file named in the format ``prNumber.type`` in
the ``newsfragments`` directory. The ``type`` can be one of the following:
* ``new`` - Used when adding new endpoints. Please have the file contents be the
method and route being added, surrounded in RST code tags. For example: ``POST
/accounts/whoami``
* ``feature`` - Used when adding backwards-compatible changes to the API.
* ``clarification`` - Used when an area of the spec is being improved upon and does
not change or introduce any functionality.
* ``breaking`` - Used when the change is not backwards compatible.
* ``deprecation`` - Used when deprecating something
All news fragments must have a brief summary explaining the change in the contents
of the file.
Changes that do not change the spec, such as changes to the build script, formatting,
CSS, etc should not get a news fragment.
Sign off
--------

4
README.rst
View file

@ -41,9 +41,9 @@ specs and event schemas in this repository.
Preparation
-----------
To use the scripts, it is best to create a Python 2.x virtualenv as follows::
To use the scripts, it is best to create a Python 3.4+ virtualenv as follows::
virtualenv env
virtualenv -p python3 env
env/bin/pip install -r scripts/requirements.txt
(Benjamin Synders has contributed a script for `Nix`_ users, which can be

340
api/application-service/application_service.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -29,8 +30,8 @@ paths:
put:
summary: Send some events to the application service.
description: |-
This API is called by the HS when the HS wants to push an event (or
batch of events) to the AS.
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
operationId: sendTransaction
parameters:
- in: path
@ -47,33 +48,33 @@ paths:
schema:
type: object
example: {
"events": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
"events": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
{
"age": 1984,
"content": {
"body": "another incoming message",
"msgtype": "m.text"
},
"event_id": "$1228055551ffsef:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
}
]
}
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
},
{
"age": 1984,
"content": {
"body": "another incoming message",
"msgtype": "m.text"
},
"event_id": "$1228055551ffsef:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
}
]
}
description: "Transaction informations"
properties:
events:
@ -88,10 +89,9 @@ paths:
description: The transaction was processed successfully.
examples:
application/json: {
}
}
schema:
type: object
"/rooms/{roomAlias}":
get:
summary: Query if a room alias should exist on the application service.
@ -119,7 +119,7 @@ paths:
before responding.
examples:
application/json: {
}
}
schema:
type: object
401:
@ -128,29 +128,29 @@ paths:
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
type: object
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
type: object
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
type: object
$ref: ../client-server/definitions/errors/error.yaml
"/users/{userId}":
get:
summary: Query if a user should exist on the application service.
@ -175,7 +175,7 @@ paths:
service MUST create the user using the client-server API.
examples:
application/json: {
}
}
schema:
type: object
401:
@ -184,26 +184,266 @@ paths:
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
type: object
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "M_FORBIDDEN"
}
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
type: object
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
type: object
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
This API is called by the homeserver when it wants to present clients
with specific information about the various third party networks that
an application service supports.
operationId: queryMetadata
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
schema:
$ref: definitions/protocol_metadata.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No protocol was found with the given path.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
This API is called by the homeserver in order to retrieve a Matrix
User ID linked to a user on the third party network, given a set of
user parameters.
operationId: queryUserByProtocol
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
- in: query
name: field1, field2...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the user.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: definitions/user_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No users were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portal rooms leading to a third party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
operationId: queryLocationByProtocol
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
- in: query
name: field1, field2...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the third party location.
responses:
200:
description: At least one portal room was found.
schema:
$ref: definitions/location_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retreive an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
responses:
200:
description: |-
All found third party locations.
schema:
$ref: definitions/location_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retreive an array of third party users from a Matrix User ID.
operationId: queryUserByID
parameters:
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
responses:
200:
description: |-
An array of third party users.
schema:
$ref: definitions/user_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

30
api/application-service/definitions/location.yaml Normal file
View file

@ -0,0 +1,30 @@
# Copyright 2018 New Vector 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.
properties:
alias:
description: An alias for a matrix room.
type: string
example: "#freenode_#matrix:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: irc
fields:
description: Information used to identify this third party location.
type: object
example:
"network": "freenode"
"channel": "#matrix"
title: Location
type: object

17
api/application-service/definitions/location_batch.yaml Normal file
View file

@ -0,0 +1,17 @@
# Copyright 2018 New Vector 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.
type: array
description: List of matched third party locations.
items:
$ref: location.yaml

79
api/application-service/definitions/protocol.yaml Normal file
View file

@ -0,0 +1,79 @@
# Copyright 2018 New Vector 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.
properties:
user_fields:
description: Fields used to identify a third party user.
type: array
items:
type: string
description: Field used to identify a third party user.
example: ["network", "nickname"]
location_fields:
description: Fields used to identify a third party location.
type: array
items:
type: string
description: Field used to identify a third party location.
example: ["network", "channel"]
icon:
description: An icon representing the third party protocol.
type: string
example: "mxc://example.org/aBcDeFgH"
field_types:
title: Field Types
description: All location or user fields should have an entry here.
type: object
properties:
fieldname:
title: Field Type
description: Definition of valid values for a field.
type: object
properties:
regexp:
description: A regular expression for validation of a field's value.
type: string
placeholder:
description: An placeholder serving as a valid example of the field value.
type: string
example: {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s#]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
}
instances:
description: |-
A list of objects representing independent instances of configuration.
For instance multiple networks on IRC if multiple are bridged by the
same bridge.
type: array
items:
type: object
example: {
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
title: Protocol
type: object

66
api/application-service/definitions/protocol_metadata.yaml Normal file
View file

@ -0,0 +1,66 @@
# Copyright 2018 New Vector 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.
type: object
description: Dictionary of supported third party protocols.
example: {
"irc": {
"user_fields": ["network", "nickname"],
"location_fields": ["network", "channel"],
"icon": "mxc://example.org/aBcDeFgH",
"field_types": {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
},
"instances": [
{
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
]
},
"gitter": {
"user_fields": ["username"],
"location_fields": ["room"],
"field_types": {
"username": {
"regexp": "@[^\\s]+",
"placeholder": "@username"
},
"room": {
"regexp": "[^\\s]+\\/[^\\s]+",
"placeholder": "matrix-org/matrix-doc"
}
},
"instances": [
{
"desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt",
"fields": {}
}
]
}
}

31
api/application-service/definitions/user.yaml Normal file
View file

@ -0,0 +1,31 @@
# Copyright 2018 New Vector 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.
# TODO: Change userid to user_id as a breaking change
properties:
userid:
description: A Matrix User ID represting a third party user.
type: string
example: "@_gitter_jim:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: gitter
fields:
description: Information used to identify this third party location.
type: object
example:
"user": "jim"
title: Location
type: object

17
api/application-service/definitions/user_batch.yaml Normal file
View file

@ -0,0 +1,17 @@
# Copyright 2018 New Vector 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.
type: array
description: List of matched third party users.
items:
$ref: user.yaml

2
api/client-server/administrative_contact.yaml
View file

@ -129,6 +129,8 @@ paths:
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
"/account/3pid/email/requestToken":

7
api/client-server/banning.yaml
View file

@ -61,7 +61,8 @@ paths:
description: The fully qualified user ID of the user being banned.
reason:
type: string
description: The reason the user has been banned.
description: The reason the user has been banned. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
@ -82,6 +83,8 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership
"/rooms/{roomId}/unban":
@ -133,5 +136,7 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

51
api/client-server/content-repo.yaml
View file

@ -72,7 +72,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}":
@ -120,7 +120,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
@ -175,7 +175,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/thumbnail/{serverName}/{mediaId}":
@ -241,7 +241,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/preview_url":
@ -296,6 +296,47 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/config":
get:
summary: Get the configuration for the content repository.
description: |-
This endpoint allows clients to retrieve the configuration of the content
repository, such as upload limitations.
Clients SHOULD use this as a guide when using content repository endpoints.
All values are intentionally left optional. Clients SHOULD follow
the advice given in the field description when the field is not available.
**NOTE:** Both clients and server administrators should be aware that proxies
between the client and the server may affect the apparent behaviour of content
repository APIs, for example, proxies may enforce a lower upload size limit
than is advertised by the server on this endpoint.
operationId: getConfig
produces: ["application/json"]
security:
- accessToken: []
responses:
200:
description: The public content repository configuration for the matrix server.
schema:
type: object
properties:
m.upload.size:
type: number
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.
If not listed or null, the size limit should be treated as unknown.
examples:
application/json: {
"m.upload.size": 50000000
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Media

32
api/client-server/create_room.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -40,7 +41,7 @@ paths:
0. A default ``m.room.power_levels`` event, giving the room creator
(and not other members) permission to send state events.
1. Events set by ``presets``.
1. Events set by the ``preset``.
2. Events listed in ``initial_state``, in the order that they are
listed.
@ -49,6 +50,16 @@ paths:
4. Invite events implied by ``invite`` and ``invite_3pid``.
The available presets do the following with respect to room state:
======================== ============== ====================== ================ =========
Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other
======================== ============== ====================== ================ =========
``private_chat`` ``invite`` ``shared`` ``can_join``
``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator.
``public_chat`` ``public`` ``shared`` ``forbidden``
======================== ============== ====================== ================ =========
operationId: createRoom
security:
- accessToken: []
@ -142,7 +153,7 @@ paths:
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
Takes precedence over events set by ``preset``, but gets
overriden by ``name`` and ``topic`` keys.
items:
type: object
@ -163,20 +174,7 @@ paths:
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``.
based on a preset.
is_direct:
type: boolean
description: |-
@ -218,6 +216,8 @@ paths:
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``).
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room creation

2
api/client-server/definitions/error.yaml → api/client-server/definitions/errors/error.yaml
View file

@ -17,7 +17,9 @@ properties:
errcode:
type: string
description: An error code.
example: M_UNKNOWN
error:
type: string
description: A human-readable error message.
example: An unknown error occurred
required: ["errcode"]

32
api/client-server/definitions/errors/rate_limited.yaml Normal file
View file

@ -0,0 +1,32 @@
# Copyright 2018 New Vector 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.
$ref: error.yaml
type: object
description: The rate limit was reached for this request
properties:
errcode:
type: string
description: The M_LIMIT_EXCEEDED error code
example: M_LIMIT_EXCEEDED
error:
type: string
description: A human-readable error message.
example: Too many requests
retry_after_ms:
type: integer
description: |-
The amount of time in milliseconds the client should wait
before trying the request again.
example: 2000
required: ["errcode"]

4
api/client-server/directory.yaml
View file

@ -68,6 +68,8 @@ paths:
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
get:
@ -118,6 +120,8 @@ paths:
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
delete:

4
api/client-server/inviting.yaml
View file

@ -93,9 +93,11 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

17
api/client-server/joining.yaml
View file

@ -110,10 +110,12 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership
"/join/{roomIdOrAlias}":
@ -143,6 +145,15 @@ paths:
description: The room identifier or alias to join.
required: true
x-example: "#monkeys:matrix.org"
- in: query
type: array
items:
type: string
name: server_name
description: |-
The servers to attempt to join the room through. One of the servers
must be participating in the room.
x-example: ["matrix.org", "elsewhere.ca"]
- in: body
name: third_party_signed
schema:
@ -206,9 +217,11 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

10
api/client-server/kicking.yaml
View file

@ -34,6 +34,10 @@ paths:
Kick a user from the room.
The caller must have the required power level in order to perform this operation.
Kicking a user adjusts the target member's membership state to be ``leave`` with an
optional ``reason``. Like with other membership changes, a user can directly adjust
the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
operationId: kick
security:
- accessToken: []
@ -59,7 +63,9 @@ paths:
description: The fully qualified user ID of the user being kicked.
reason:
type: string
description: The reason the user has been kicked.
description: |-
The reason the user has been kicked. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
@ -81,5 +87,7 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

17
api/client-server/leaving.yaml
View file

@ -64,7 +64,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership
"/rooms/{roomId}/forget":
@ -78,8 +78,8 @@ paths:
for this room. If all users on a homeserver forget a room, the room is
eligible for deletion from that homeserver.
If the user is currently joined to the room, they will implicitly leave
the room as part of this API call.
If the user is currently joined to the room, they must leave the room
before calling this API.
operationId: forgetRoom
security:
- accessToken: []
@ -99,9 +99,18 @@ paths:
}
schema:
type: object
400:
description: The user has not left the room
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

4
api/client-server/list_public_rooms.yaml
View file

@ -59,6 +59,8 @@ paths:
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
put:
summary: Sets the visibility of a room in the room directory
description: |-
@ -107,6 +109,8 @@ paths:
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/publicRooms":
get:
summary: Lists the public rooms on the server.

8
api/client-server/login.yaml
View file

@ -61,7 +61,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management
post:
@ -167,15 +167,19 @@ paths:
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The login attempt failed. For example, the password may have been incorrect.
examples:
application/json: {
"errcode": "M_FORBIDDEN"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management

1
api/client-server/message_pagination.yaml
View file

@ -107,6 +107,7 @@ paths:
items:
type: object
title: RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
examples:
application/json: {
"start": "t47429-4392820_219380_26003_2265",

17
api/client-server/presence.yaml
View file

@ -75,7 +75,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Presence
get:
@ -83,6 +83,8 @@ paths:
description: |-
Get the given user's presence state.
operationId: getPresence
security:
- accessToken: []
parameters:
- in: path
type: string
@ -121,6 +123,17 @@ paths:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: You are not allowed to see this user's presence status.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to see their presence"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Presence
"/presence/list/{userId}":
@ -176,7 +189,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Presence
get:

4
api/client-server/profile.yaml
View file

@ -67,7 +67,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
get:
@ -141,7 +141,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
get:

4
api/client-server/pusher.yaml
View file

@ -228,10 +228,10 @@ paths:
"errcode": "M_MISSING_PARAM"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Push notifications

4
api/client-server/pushrules.yaml
View file

@ -438,11 +438,11 @@ paths:
"errcode": "M_UNKNOWN"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/enabled":

2
api/client-server/receipts.yaml
View file

@ -76,6 +76,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room participation

14
api/client-server/registration.yaml
View file

@ -177,6 +177,8 @@ paths:
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
@ -185,7 +187,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/register/email/requestToken":
@ -249,7 +251,7 @@ paths:
"error": "The specified address is already in use"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
"/account/password":
post:
summary: "Changes a user's password."
@ -296,7 +298,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/password/email/requestToken":
@ -363,7 +365,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/register/available":
@ -420,9 +422,11 @@ paths:
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

24
api/client-server/search.yaml
View file

@ -74,7 +74,7 @@ paths:
properties:
room_events:
type: object
title: "Room Events"
title: Room Events Criteria
description: Mapping of category name to search criteria.
properties:
search_term:
@ -103,7 +103,7 @@ paths:
The order in which to search for results.
By default, this is ``"rank"``.
event_context:
title: "Event Context"
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
@ -169,13 +169,13 @@ paths:
properties:
search_categories:
type: object
title: Categories
title: Result Categories
description: Describes which categories to search in and
their criteria.
properties:
room_events:
type: object
title: Room Event Results
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
count:
@ -227,6 +227,9 @@ paths:
description: |-
The historic profile information of the
users that sent the events returned.
The ``string`` key is the user ID for which
the profile belongs to.
additionalProperties:
type: object
title: User Profile
@ -260,15 +263,24 @@ paths:
The current state for every room in the results.
This is included if the request had the
``include_state`` key set with a value of ``true``.
The ``string`` key is the room ID for which the ``State
Event`` array belongs to.
additionalProperties:
type: array
title: Room State
items:
type: object
"$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
groups:
type: object
title: Groups
description: Any groups that were requested.
description: |-
Any groups that were requested.
The outer ``string`` key is the group key requested (eg: ``room_id``
or ``sender``). The inner ``string`` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
title: Group Key
@ -355,6 +367,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Search

194
api/client-server/third_party_lookup.yaml Normal file
View file

@ -0,0 +1,194 @@
# Copyright 2018 New Vector 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 Third Party Lookup 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:
"/thirdparty/protocols":
get:
summary: Retrieve metadata about all protocols that a homeserver supports.
description: |-
Fetches the overall metadata about protocols supported by the
homeserver. Includes both the available protocols and all fields
required for queries against each protocol.
operationId: queryMetadata
responses:
200:
description: The protocols supported by the homeserver.
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the homeserver supports.
description: |-
Fetches the metadata from the homeserver about a particular third party protocol.
operationId: queryMetadata
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
schema:
$ref: ../application-service/definitions/protocol.yaml
404:
description: The protocol is unknown.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/location/{protocol}":
get:
summary: Retreive Matrix-side portals rooms leading to a third party location.
description: |-
Requesting this endpoint with a valid protocol name results in a list
of successful mapping results in a JSON array. Each result contains
objects to represent the Matrix room or rooms that represent a portal
to this third party network. Each has the Matrix room alias string,
an identifier for the particular third party network protocol, and an
object containing the network-specific fields that comprise this
identifier. It should attempt to canonicalise the identifier as much
as reasonably possible given the network type.
operationId: queryLocationByProtocol
parameters:
- in: path
name: protocol
type: string
description: The protocol used to communicate to the third party network.
required: true
x-example: irc
- in: query
name: searchFields
type: string
description: |-
One or more custom fields to help identify the third party
location.
responses:
200:
description: At least one portal room was found.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
description: No portal rooms were found.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
Retrieve a Matrix User ID linked to a user on the third party service, given
a set of user parameters.
operationId: queryUserByProtocol
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
required: true
x-example: irc
- in: query
name: field1, field2...
type: string
description: |-
One or more custom fields that are passed to the AS to help identify the user.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retreive an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
required: true
responses:
200:
description: |-
All found third party locations.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
description: The Matrix room alias was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retreive an array of third party users from a Matrix User ID.
operationId: queryUserByID
parameters:
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
required: true
responses:
200:
description: |-
An array of third party users.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml

4
api/client-server/third_party_membership.yaml
View file

@ -126,9 +126,11 @@ paths:
examples:
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

2
api/client-server/typing.yaml
View file

@ -82,6 +82,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room participation

2
api/client-server/users.yaml
View file

@ -95,6 +95,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

2
api/client-server/voip.yaml
View file

@ -73,6 +73,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- VOIP

6
api/client-server/whoami.yaml
View file

@ -65,7 +65,7 @@ paths:
"error": "Unrecognised access token."
}
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
403:
description:
The appservice cannot masquerade as the user or has not registered them.
@ -75,10 +75,10 @@ paths:
"error": "Application service has not registered this user."
}
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

40
api/server-server/definitions/edu.yaml Normal file
View file

@ -0,0 +1,40 @@
# Copyright 2018 New Vector 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.
# TODO: Address any concerns about this being inaccurate (flagged as such in the EDUs section)
type: object
title: Ephemeral Data Unit
description: An ephemeral data unit
example:
$ref: "../examples/edu.json"
properties:
edu_type:
type: string
description: The type of ephemeral message.
example: "m.presence"
required: true
origin:
type: string
description: The server name sending the ephemeral message.
example: "matrix.org"
required: true
destination:
type: string
description: The server name receiving the ephemeral message.
example: "elsewhere.com"
required: true
content:
type: object
description: The content of the ephemeral message.

96
api/server-server/definitions/keys.yaml Normal file
View file

@ -0,0 +1,96 @@
# Copyright 2018 New Vector 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.
type: object
title: Server Keys
description: Server keys
example:
$ref: "../examples/server_key.json"
properties:
server_name:
type: string
description: DNS name of the homeserver.
required: true # TODO: Verify
example: "example.org"
verify_keys:
type: object
description: Public keys of the homeserver for verifying digital signatures.
required: true # TODO: Verify
additionalProperties:
type: object
title: Verify Key
example: {
"ed25519:auto2": {
"key": "Base+64+Encoded+Signature+Verification+Key"
}
}
properties:
key:
type: string
description: The key
required: true
example: "Base+64+Encoded+Signature+Verification+Key"
old_verify_keys:
type: object
description: The public keys that the server used to use and when it stopped using them.
additionalProperties:
type: object
title: Old Verify Key
example: {
"ed25519:auto1": {
"expired_ts": 922834800000,
"key": "Base+64+Encoded+Signature+Verification+Key"
}
}
properties:
expired_ts:
type: integer
format: int64
description: The expiration time.
required: true
example: 922834800000
key:
type: string
description: The key.
required: true
example: "Base+64+Encoded+Signature+Verification+Key"
signatures:
type: object
description: Digital signatures for this object signed using the ``verify_keys``.
additionalProperties:
type: object
title: Signed Server
example: {
"example.org": {
"ad25519:auto2": "Base+64+Encoded+Signature+Verification+Key"
}
}
additionalProperties:
type: string
name: Encoded Signature Verification Key
tls_fingerprints:
type: array
description: Hashes of X.509 TLS certificates used by this server encoded as `Unpadded Base64`_.
items:
type: object
title: TLS Fingerprint
properties:
sha256:
type: string
description: The encoded fingerprint.
example: Base+64+Encoded+SHA-256-Fingerprint
valid_until_ts:
type: integer
format: int64
description: POSIX timestamp when the list of valid keys should be refreshed.
example: 1052262000000

27
api/server-server/definitions/keys_query_response.yaml Normal file
View file

@ -0,0 +1,27 @@
# Copyright 2018 New Vector 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.
type: object
description: Server keys
example: {
"server_keys": [{
$ref: "../examples/server_key.json"
}]
}
properties:
server_keys:
type: array
title: Server Keys
description: The server keys.
items:
$ref: "keys.yaml"

52
api/server-server/definitions/pdu.yaml Normal file
View file

@ -0,0 +1,52 @@
# Copyright 2018 New Vector 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.
type: object
title: Persistent Data Unit
description: A persistent data unit (event)
example:
$ref: "../examples/pdu.json"
allOf:
- $ref: "unsigned_pdu.yaml"
- type: object
properties:
hashes:
type: object
title: Event Hash
description: Hashes of the PDU, following the algorithm specified in `Signing Events`_.
example: {
"sha256": "thishashcoversallfieldsincasethisisredacted"
}
properties:
sha256:
type: string
description: The hash.
example: thishashcoversallfieldsincasthisisredacted
required: ['sha256']
signatures:
type: object
description: |-
Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_.
example: {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
}
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
required:
- hashes
- signatures

35
api/server-server/definitions/transaction.yaml Normal file
View file

@ -0,0 +1,35 @@
# Copyright 2018 New Vector 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.
type: object
title: Transaction
description: Transaction
example:
$ref: "../examples/transaction.json"
properties:
origin:
type: string
description: |-
The ``server_name`` of the homeserver sending this transaction.
example: "example.org"
origin_server_ts:
type: integer
format: int64
description: Timestamp in milliseconds on originating homeserver when this transaction started.
example: 1234567890
pdus:
type: array
description: List of persistent updates to rooms.
items:
$ref: "pdu.yaml"
required: ['origin', 'origin_server_ts', 'pdus']

118
api/server-server/definitions/unsigned_pdu.yaml Normal file
View file

@ -0,0 +1,118 @@
# Copyright 2018 New Vector 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.
type: object
title: Unsigned Persistent Data Unit
description: An unsigned persistent data unit (event)
example:
$ref: "../examples/unsigned_pdu.json"
properties:
room_id:
type: string
description: Room identifier.
example: "!abc123:matrix.org"
sender:
type: string
description: The ID of the user sending the event.
example: "@someone:matrix.org"
origin:
type: string
description: The ``server_name`` of the homeserver that created this event.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: Timestamp in milliseconds on origin homeserver when this event was created.
example: 1234567890
type:
type: string
description: Event type
example: "m.room.message"
state_key:
type: string
description: |-
If this key is present, the event is a state event, and it will replace previous events
with the same ``type`` and ``state_key`` in the room state.
example: "my_key"
content:
type: object
description: The content of the event.
example: {"key": "value"}
prev_events:
type: array
description: |-
Event IDs and hashes of the most recent events in the room that the homeserver was aware
of when it made this event.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
depth:
type: integer
description: The maximum depth of the ``prev_events``, plus one.
example: 12
auth_events:
type: array
description: Event IDs and hashes for the "auth events" of this event.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def456:matrix.org"
unsigned:
type: object
description: Additional data added by the origin server but not covered by the ``signatures``.
example: {"key": "value"}
required:
- room_id
- sender
- origin
- origin_server_ts
- type
- content
- prev_events
- depth
- auth_events

3
api/server-server/directory.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2017 Kamax.io
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -14,7 +15,7 @@
swagger: '2.0'
info:
title: "Matrix Federation Query Directory API"
title: "Matrix Federation Query API"
version: "1.0.0"
host: localhost:8448
schemes:

93
api/server-server/events.yaml Normal file
View file

@ -0,0 +1,93 @@
# Copyright 2018 New Vector 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 Federation Events API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/state/{roomId}":
get:
summary: Get all the state of a given room
description: |-
Retrieves a snapshot of the entire current state of the given room.
operationId: getRoomState
parameters:
- in: path
name: roomId
type: string
description: The room ID to get state for.
required: true
x-example: "!abc123:matrix.org"
responses:
200:
description: The room state for the room (kept under ``pdus``).
schema:
$ref: "definitions/transaction.yaml"
"/event/{eventId}":
get:
summary: Get a single event
description: |-
Retrieves a single event.
operationId: getEvent
parameters:
- in: path
name: eventId
type: string
description: The event ID to get.
required: true
x-example: "$abc123:matrix.org"
responses:
200:
description: A transaction containing a single PDU which is the event requested.
schema:
$ref: "definitions/transaction.yaml"
"/backfill/{roomId}":
get:
summary: Retrieves the events which precede the given event
description: |-
Retreives a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
are retrieved, up to the total number given by the ``limit``.
operationId: backfillRoom
parameters:
- in: path
name: roomId
type: string
description: The room ID to backfill.
required: true
x-example: "!abc123:matrix.org"
- in: query
name: v
type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it
description: The event ID to backfill from.
required: true
x-example: "$abc123:matrix.org"
- in: query
name: limit
type: integer
description: The maximum number of events to retrieve.
required: true
x-example: 10
responses:
200:
description: A transaction containing the PDUs that preceded the given event(s).
schema:
$ref: "definitions/transaction.yaml"

8
api/server-server/examples/edu.json Normal file
View file

@ -0,0 +1,8 @@
{
"edu_type": "m.presence",
"origin": "blue",
"destination": "orange",
"content": {
"key": "value"
}
}

11
api/server-server/examples/pdu.json Normal file
View file

@ -0,0 +1,11 @@
{
"$ref": "unsigned_pdu.json",
"hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted"
},
"signatures": {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
}
}

23
api/server-server/examples/server_key.json Normal file
View file

@ -0,0 +1,23 @@
{
"server_name": "example.org",
"verify_keys": {
"ed25519:auto2": {
"key": "Base+64+Encoded+Signature+Verification+Key"
}
},
"old_verify_keys": {
"ed25519:auto1": {
"expired_ts": 922834800000,
"key": "Base+64+Encoded+Old+Verify+Key"
}
},
"signatures": {
"example.org": {
"ed25519:auto2": "Base+64+Encoded+Signature"
}
},
"tls_fingerprints": [{
"sha256": "Base+64+Encoded+SHA-256-Fingerprint"
}],
"valid_until_ts": 1052262000000
}

5
api/server-server/examples/transaction.json Normal file
View file

@ -0,0 +1,5 @@
{
"origin": "matrix.org",
"origin_server_ts": 1234567890,
"pdus": [{"$ref": "pdu.json"}]
}

17
api/server-server/examples/unsigned_pdu.json Normal file
View file

@ -0,0 +1,17 @@
{
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
"sender": "@alice:example.com",
"origin": "example.com",
"event_id": "$a4ecee13e2accdadf56c1025:example.com",
"origin_server_ts": 1404838188000,
"type": "m.room.message",
"prev_events": [
[
"$af232176:example.org",
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
]
],
"content": {
"key": "value"
}
}

99
api/server-server/keys_query.yaml Normal file
View file

@ -0,0 +1,99 @@
# Copyright 2018 New Vector 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 Federation Key Exchange API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/key/v2
produces:
- application/json
paths:
"/query/{serverName}/{keyId}":
get:
summary: Retrieve a server key.
description: Retrieve a server key.
operationId: perspectivesKeyQuery
parameters:
- in: path
name: serverName
type: string
description: Server name.
required: true
x-example: matrix.org
- in: path
name: keyId
type: string
description: Key ID.
required: true
x-example: TODO # No examples in spec so far
- in: query
name: minimum_valid_until_ts
type: integer
format: int64
description: Minimum Valid Until Milliseconds.
required: true # TODO: Verify
x-example: 1234567890
responses:
200:
description: The keys for the server
schema:
$ref: "definitions/keys_query_response.yaml"
"/query":
post:
summary: Retrieve a server key
description: Retrieve a server key.
operationId: bulkPerspectivesKeyQuery
parameters:
- in: body
name: body
schema:
type: object
# TODO: Improve example
example: {
"server_keys": {
"{server_name}": {
"{key_id}": {
"minimum_valid_until_ts": 1234567890
}
}
}
}
properties:
server_keys:
type: object
description: The query criteria.
additionalProperties:
type: object
name: ServerName
description: The server names to query.
additionalProperties:
type: object
title: Query Criteria
description: The server keys to query.
properties:
minimum_valid_until_ts:
type: integer
format: int64
description: Minimum Valid Until MS.
example: 1234567890
required: ['server_keys']
responses:
200:
description: The keys for the server.
schema:
$ref: "definitions/keys_query_response.yaml"

42
api/server-server/keys_server.yaml Normal file
View file

@ -0,0 +1,42 @@
# Copyright 2018 New Vector 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 Federation Key Exchange API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/key/v2
produces:
- application/json
paths:
"/server/{keyId}":
get:
summary: Get the server's key
description: Get the server's key.
operationId: getServerKey
parameters:
- in: path
name: keyId
type: string
description: Key ID
required: false
x-example: TODO # No examples in the spec so far
responses:
200:
description: The server's keys.
schema:
$ref: "definitions/keys.yaml"

44
api/server-server/query_general.yaml Normal file
View file

@ -0,0 +1,44 @@
# Copyright 2018 New Vector 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 Federation Query API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/query/{queryType}":
get:
summary: Query for information
description: |-
Performs a single query request on the receiving homeserver. The query string
arguments are dependent on which type of query is being made. Known query types
are specified as their own endpoints as an extension to this definition.
operationId: queryInfo
parameters:
- in: path
name: queryType
type: string
description: The type of query to make
required: true
x-example: profile
responses:
200:
description: |-
The query response. The schema varies depending on the query being made.

190
api/server-server/third_party_invite.yaml Normal file
View file

@ -0,0 +1,190 @@
# Copyright 2018 New Vector 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 Federation Third Party Invites API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/exchange_third_party_invite/{roomId}":
put:
summary: Request a server to auth a third party invite event
description: |-
The receiving server will verify the partial ``m.room.member`` event
given in the request body. If valid, the receiving server will issue
an invite as per the `Inviting to a room`_ section before returning a
response to this request.
operationId: exchangeThirdPartyInvite
parameters:
- in: path
name: roomId
type: string
description: The room ID to exchange a third party invite in
required: true
x-example: "!abc123:matrix.org"
- in: body
name: body
type: object
description: A partial ``m.room.member`` event
required: true
schema:
type: object
properties:
type:
type: string
description: The event type. Must be ``m.room.member``
example: "m.room.member"
room_id:
type: string
description: |-
The room ID the event is for. Must match the ID given in
the path.
example: "!abc123:matrix.org"
sender:
type: string
description: |-
The user ID of the user who sent the original ``m.room.third_party_invite``
event.
example: "@joe:matrix.org"
state_key:
type: string
description: The user ID of the invited user
example: "@someone:example.org"
content:
type: object
description: The event content
title: Event Content
properties:
membership:
type: string
description: The membership state. Must be ``invite``
example: invite
third_party_invite:
type: object
description: The third party invite
properties:
display_name:
type: string
description: |-
A name which can be displayed to represent the user instead of their
third party identifier.
example: "alice"
signed:
type: object
description: |-
A block of content which has been signed, which servers can use to
verify the event.
properties:
signatures:
type: object
description: The server signatures for this event.
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
example: {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
mxid:
type: string
description: The invited matrix user ID
example: "@alice:localhost"
token:
type: string
description: The token used to verify the event
example: abc123
required: ['signatures', 'mxid', 'token']
example: {
"mxid": "@alice:localhost",
"token": "abc123",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}
required: ['display_name', 'signed']
example: {
"display_name": "alice",
"signed": {
"mxid": "@alice:localhost",
"token": "abc123",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}
}
required: ['membership', 'third_party_invite']
example: {
"membership": "invite",
"third_party_invite": {
"display_name": "alice",
"signed": {
"mxid": "@alice:localhost",
"token": "abc123",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}
}
}
required:
- type
- room_id
- sender
- state_key
- content
example: {
"type": "m.room.member",
"room_id": "!abc123:matrix.org",
"sender": "@joe:matrix.org",
"state_key": "@someone:example.org",
"content": {
"membership": "invite",
"third_party_invite": {
"display_name": "alice",
"signed": {
"mxid": "@alice:localhost",
"token": "abc123",
"signatures": {
"magic.forest": {
"ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
}
}
}
}
}
}
responses:
200:
description: The invite has been issued successfully.
examples:
application/json: {}
schema:
type: object
description: An empty object
example: {}

64
api/server-server/transactions.yaml Normal file
View file

@ -0,0 +1,64 @@
# Copyright 2018 New Vector 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 Federation Transaction API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
produces:
- application/json
paths:
"/send/{txnId}":
put:
summary: Send a transaction
description: |-
Push messages representing live activity to another server. The destination name
will be set to that of the receiving server itself. Each embedded PDU in the
transaction body will be processed.
operationId: sendTransaction
parameters:
- in: path
name: txnId
type: string
# TODO: "Overrides any ID given in the JSON body" - What does this mean?
description: |-
The transaction ID. Overrides any ID given in the JSON body.
required: true
x-example: TODO # No examples in the spec so far
- in: body
name: body
type: object
required: true
schema:
allOf:
- $ref: "definitions/transaction.yaml"
- type: object
properties:
edus:
type: array
description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
items:
$ref: "definitions/edu.yaml"
example: {
"$ref": "examples/transaction.json",
"edus": [{"$ref": "edu.json"}] # Relative to the examples directory
}
responses:
200:
# TODO: Spec this (and figure out what it is)
description: TODO

55
changelogs/README.md Normal file
View file

@ -0,0 +1,55 @@
<!-- Note: This is a markdown file so the build script's RST processing doesn't grab it -->
# Changelogs
[Towncrier](https://github.com/hawkowl/towncrier) is used to manage the changelog and
keep it up to date. Because of this, updating a changelog is really easy.
## How to update a changelog when releasing an API
1. Ensure you're in your Python 3 virtual environment
2. `cd` your way to the API you're releasing (eg: `cd changelogs/client_server`)
3. Run `towncrier --version "r0.4.0" --name "client-server" --yes` substituting the
variables as approprite. Note that `--name` is required although the value is ignored.
4. Commit the changes and finish the release process.
## How to prepare a changelog for a new API
For this example, we're going to pretend that the `server_server` API doesn't exist.
1. Create the file `changelogs/server_server.rst`
2. Create the folder `changelogs/server_server`
3. In the new folder, create a `pyproject.toml` file with these contents:
```toml
[tool.towncrier]
filename = "../server_server.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true
```
4. Create a `.gitignore` in `changelogs/server_server/newsfragments` with the contents `!.gitignore`

63
changelogs/client_server.rst
View file

@ -1,66 +1,3 @@
Unreleased changes
==================
- Changes to the API which will be backwards-compatible for clients:
- New endpoints:
- ``POST /user_directory/search``
(`#1096 <https://github.com/matrix-org/matrix-doc/pull/1096>`_).
- ``GET /rooms/{roomId}/event/{eventId}``
(`#1110 <https://github.com/matrix-org/matrix-doc/pull/1110>`_).
- ``POST /delete_devices``
(`#1239 <https://github.com/matrix-org/matrix-doc/pull/1239>`_).
- Sticker messages:
- Add sticker message event definition.
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
- Document the GET version of ``/login``
(`#1361 <https://github.com/matrix-org/matrix-doc/pull/1361>`_).
- Spec clarifications:
- Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions
to clarify that they relate to intended display size, as opposed to the
intrinsic size of the image file.
(`#1158 <https://github.com/matrix-org/matrix-doc/pull/1158>`_).
- Mark ``home_server`` return field for ``/login`` and ``/register``
endpoints as deprecated
(`#1097 <https://github.com/matrix-org/matrix-doc/pull/1097>`_).
- Fix response format of ``/keys/changes`` endpoint
(`#1106 <https://github.com/matrix-org/matrix-doc/pull/1106>`_).
- Clarify default values for some fields on the /search API
(`#1109 <https://github.com/matrix-org/matrix-doc/pull/1109>`_).
- Fix the representation of ``m.presence`` events
(`#1137 <https://github.com/matrix-org/matrix-doc/pull/1137>`_).
- Clarify that ``m.tag`` ordering is done with numbers, not strings
(`#1139 <https://github.com/matrix-org/matrix-doc/pull/1139>`_).
- Clarify that ``/account/whoami`` should consider application services
(`#1152 <https://github.com/matrix-org/matrix-doc/pull/1152>`_).
- Mark ``GET /rooms/{roomId}/members`` as requiring authentication
(`#1245 <https://github.com/matrix-org/matrix-doc/pull/1244>`_).
- Describe ``StateEvent`` for ``/createRoom``
(`#1329 <https://github.com/matrix-org/matrix-doc/pull/1329>`_).
- Changes to the API which will be backwards-compatible for clients:
- Add 'token' parameter to /keys/query endpoint
(`#1104 <https://github.com/matrix-org/matrix-doc/pull/1104>`_).
- Add the room visibility options for the room directory
(`#1141 <https://github.com/matrix-org/matrix-doc/pull/1141>`_).
- Add spec for ignoring users
(`#1142 <https://github.com/matrix-org/matrix-doc/pull/1142>`_).
- Add the ``/register/available`` endpoint for username availability
(`#1151 <https://github.com/matrix-org/matrix-doc/pull/1151>`_).
- Add ``allow_remote`` to the content repo to avoid routing loops
(`#1265 <https://github.com/matrix-org/matrix-doc/pull/1265>`_).
- Add report content API
(`#1264 <https://github.com/matrix-org/matrix-doc/pull/1264>`_).
- Document ``/logout/all`` endpoint
(`#1263 <https://github.com/matrix-org/matrix-doc/pull/1263>`_).
- Document `highlights` field in /search response
(`#1274 <https://github.com/matrix-org/matrix-doc/pull/1274>`_).
r0.3.0
======

1
changelogs/client_server/newsfragments/.gitignore vendored Normal file
View file

@ -0,0 +1 @@
!.gitignore

1
changelogs/client_server/newsfragments/1096.new Normal file
View file

@ -0,0 +1 @@
``POST /user_directory/search``

1
changelogs/client_server/newsfragments/1097.clarification Normal file
View file

@ -0,0 +1 @@
Mark ``home_server`` return field for ``/login`` and ``/register`` endpoints as deprecated

1
changelogs/client_server/newsfragments/1104.feature Normal file
View file

@ -0,0 +1 @@
Add ``token`` parameter to the ``/keys/query`` endpoint

1
changelogs/client_server/newsfragments/1106.clarification Normal file
View file

@ -0,0 +1 @@
Fix response format of ``/keys/changes`` endpoint

1
changelogs/client_server/newsfragments/1109.clarification Normal file
View file

@ -0,0 +1 @@
Clarify default values for some fields on the ``/search`` API

1
changelogs/client_server/newsfragments/1110.new Normal file
View file

@ -0,0 +1 @@
``GET /rooms/{roomId}/event/{eventId}``

1
changelogs/client_server/newsfragments/1137.clarification Normal file
View file

@ -0,0 +1 @@
Fix the representation of ``m.presence`` events

1
changelogs/client_server/newsfragments/1139.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that ``m.tag`` ordering is done with numbers, not strings

1
changelogs/client_server/newsfragments/1141.feature Normal file
View file

@ -0,0 +1 @@
Add the room visibility options for the room directory

1
changelogs/client_server/newsfragments/1142.feature Normal file
View file

@ -0,0 +1 @@
Add spec for ignoring users

1
changelogs/client_server/newsfragments/1151.feature Normal file
View file

@ -0,0 +1 @@
Add the ``/register/available`` endpoint for username availability

1
changelogs/client_server/newsfragments/1152.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that ``/account/whoami`` should consider application services

3
changelogs/client_server/newsfragments/1158.clarification Normal file
View file

@ -0,0 +1,3 @@
Update ``ImageInfo`` and ``ThumbnailInfo`` dimension schema descriptions
to clarify that they relate to intended display size, as opposed to the
intrinsic size of the image file.

1
changelogs/client_server/newsfragments/1158.feature Normal file
View file

@ -0,0 +1 @@
Add sticker messages

1
changelogs/client_server/newsfragments/1239.new Normal file
View file

@ -0,0 +1 @@
``POST /delete_devices``

1
changelogs/client_server/newsfragments/1245.clarification Normal file
View file

@ -0,0 +1 @@
Mark ``GET /rooms/{roomId}/members`` as requiring authentication

1
changelogs/client_server/newsfragments/1263.feature Normal file
View file

@ -0,0 +1 @@
Document ``/logout/all`` endpoint

1
changelogs/client_server/newsfragments/1264.feature Normal file
View file

@ -0,0 +1 @@
Add report content API

1
changelogs/client_server/newsfragments/1265.feature Normal file
View file

@ -0,0 +1 @@
Add ``allow_remote`` to the content repo to avoid routing loops

1
changelogs/client_server/newsfragments/1274.feature Normal file
View file

@ -0,0 +1 @@
Document `highlights` field in /search response

1
changelogs/client_server/newsfragments/1329.clarification Normal file
View file

@ -0,0 +1 @@
Describe ``StateEvent`` for ``/createRoom``

1
changelogs/client_server/newsfragments/1353.new Normal file
View file

@ -0,0 +1 @@
``GET /thirdparty/*`` Endpoints

1
changelogs/client_server/newsfragments/1361.feature Normal file
View file

@ -0,0 +1 @@
Document the GET version of ``/login``

1
changelogs/client_server/newsfragments/1362.clarification Normal file
View file

@ -0,0 +1 @@
Describe how the ``reason`` is handled for kicks/bans

1
changelogs/client_server/newsfragments/1364.feature Normal file
View file

@ -0,0 +1 @@
Document the ``server_name`` parameter on ``/join/{roomIdOrAlias}``

1
changelogs/client_server/newsfragments/1365.feature Normal file
View file

@ -0,0 +1 @@
Document the CORS/preflight headers

1
changelogs/client_server/newsfragments/1371.clarification Normal file
View file

@ -0,0 +1 @@
Mark ``GET /presence/{userId}/status`` as requiring authentication

1
changelogs/client_server/newsfragments/1373.clarification Normal file
View file

@ -0,0 +1 @@
Describe the rate limit error response schema

1
changelogs/client_server/newsfragments/1378.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that clients must leave rooms before forgetting them

1
changelogs/client_server/newsfragments/1379.clarification Normal file
View file

@ -0,0 +1 @@
Document guest access in ``/createRoom`` presets

1
changelogs/client_server/newsfragments/1380.clarification Normal file
View file

@ -0,0 +1 @@
Define what a ``RoomEvent`` is on ``/rooms/{roomId}/messages``

1
changelogs/client_server/newsfragments/1381.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the request and result types on ``/search``

1
changelogs/client_server/newsfragments/1397.feature Normal file
View file

@ -0,0 +1 @@
Document message formats on ``m.text`` and ``m.emote`` messages

1
changelogs/client_server/newsfragments/1400.clarification Normal file
View file

@ -0,0 +1 @@
Clarify some of the properties on the search result

30
changelogs/client_server/pyproject.toml Normal file
View file

@ -0,0 +1,30 @@
[tool.towncrier]
filename = "../client_server.rst"
directory = "newsfragments"
issue_format = "`#{issue} <https://github.com/matrix-org/matrix-doc/issues/{issue}>`_"
title_format = "{version}"
[[tool.towncrier.type]]
directory = "breaking"
name = "Breaking Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "deprecation"
name = "Deprecations"
showcontent = true
[[tool.towncrier.type]]
directory = "new"
name = "New Endpoints"
showcontent = true
[[tool.towncrier.type]]
directory = "feature"
name = "Backwards Compatible Changes"
showcontent = true
[[tool.towncrier.type]]
directory = "clarification"
name = "Spec Clarifications"
showcontent = true

4
event-schemas/examples/m.room.message#m.emote
View file

@ -2,7 +2,9 @@
"age": 242352,
"content": {
"body": "thinks this is an example emote",
"msgtype": "m.emote"
"msgtype": "m.emote",
"format": "org.matrix.custom.html",
"formatted_body": "thinks <b>this</b> is an example emote"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",

4
event-schemas/examples/m.room.message#m.text
View file

@ -2,7 +2,9 @@
"age": 242352,
"content": {
"body": "This is an example text message",
"msgtype": "m.text"
"msgtype": "m.text",
"format": "org.matrix.custom.html",
"formatted_body": "<b>This is an example text message</b>"
},
"origin_server_ts": 1431961217939,
"event_id": "$WLGTSEFSEF:localhost",

10
event-schemas/schema/m.room.message#m.emote
View file

@ -12,6 +12,16 @@ properties:
enum:
- m.emote
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
is specified.
type: string
required:
- msgtype
- body

10
event-schemas/schema/m.room.message#m.text
View file

@ -12,6 +12,16 @@ properties:
enum:
- m.text
type: string
format:
description: |-
The format used in the ``formatted_body``. Currently only
``org.matrix.custom.html`` is supported.
type: string
formatted_body:
description: |-
The formatted version of the ``body``. This is required if ``format``
is specified.
type: string
required:
- msgtype
- body

9
pyproject.toml Normal file
View file

@ -0,0 +1,9 @@
[ tool.giles ]
[ tool.giles.circleci_artifacts.docs ]
url = "gen/index.html"
message = "Click details to preview the HTML documentation."
[ tool.giles.circleci_artifacts.swagger ]
url = "client-server/index.html"
message = "Click to preview the swagger build."

Some files were not shown because too many files have changed in this diff Show more