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

Merge pull request #2518 from matrix-org/kitsune/cleanup

Browse source 
Assorted cleanup pieces
This commit is contained in:
Kitsune Ral 2020-07-23 08:42:41 +02:00 • committed by GitHub
commit 5a699f2650
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
24 changed files with 116 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.rst
View file

@ -46,7 +46,7 @@ To use the scripts, it is best to create a Python 3.4+ virtualenv as follows::
virtualenv -p python3 env
env/bin/pip install -r scripts/requirements.txt
(Benjamin Synders has contributed a script for `Nix`_ users, which can be
(Benjamin Saunders has contributed a script for `Nix`_ users, which can be
invoked with ``nix-shell scripts/contrib/shell.nix``.)
.. TODO: Possibly we need some libs installed; should record what they are.

3
api/application-service/transactions.yaml
View file

@ -50,7 +50,7 @@ paths:
x-example: "35"
- in: body
name: body
description: A list of events.
description: Transaction information
schema:
type: object
example: {
@ -59,7 +59,6 @@ paths:
{"$ref": "../../event-schemas/examples/m.room.message$m.text"}
]
}
description: Transaction information
properties:
events:
type: array

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

@ -108,6 +108,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -195,6 +196,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -202,7 +204,8 @@ paths:
description: |-
Additional authentication information for the
user-interactive authentication API.
$ref: "definitions/auth_data.yaml"
allOf:
- $ref: "definitions/auth_data.yaml"
client_secret:
type: string
description: The client secret used in the session with the homeserver.
@ -247,6 +250,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -299,6 +303,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -363,6 +368,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -427,7 +433,7 @@ paths:
name: body
required: true
schema:
$ref: "./definitions/request_email_validation.yaml"
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: |-
@ -477,7 +483,7 @@ paths:
name: body
required: true
schema:
$ref: "./definitions/request_msisdn_validation.yaml"
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.

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

@ -163,9 +163,11 @@ paths:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: |-
Download content from the content repository. This is the same as
the download endpoint above, except permitting a desired file name.
summary: Download content from the content repository overriding the file name
description: |-
This will download content from the content repository (same as
the previous endpoint) but replace the target file name with the one
provided by the caller.
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
@ -233,9 +235,10 @@ paths:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: |-
Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
section for more information.
summary: Download a thumbnail of content from the content repository
description: |-
Download a thumbnail of content from the content repository.
See the `thumbnailing <#thumbnails>`_ section for more information.
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
@ -283,10 +286,10 @@ paths:
x-example: false
required: false
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
description: |-
Indicates to the server that it should not attempt to fetch
the media if it is deemed remote. This is to prevent routing loops
where the server contacts itself. Defaults to true if not provided.
responses:
200:
description: "A thumbnail of the requested content."

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

@ -80,6 +80,7 @@ paths:
- in: body
name: body
description: The desired room configuration.
required: true
schema:
type: object
example: {

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

@ -121,7 +121,7 @@ paths:
description: |-
The new display name for this device. If not given, the
display name is unchanged.
example: My other phone
example: { "display_name": "My other phone" }
responses:
200:
description: The device was successfully updated.
@ -152,6 +152,7 @@ paths:
x-example: "QBUAZIFURK"
- in: body
name: body
required: true
schema:
type: object
properties:
@ -159,7 +160,8 @@ paths:
description: |-
Additional authentication information for the
user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
allOf:
- "$ref": "definitions/auth_data.yaml"
responses:
200:
description: |-
@ -190,6 +192,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -201,10 +204,11 @@ paths:
description: A list of device IDs.
example: ["QBUAZIFURK", "AUIECTSRND"]
auth:
allOf:
- "$ref": "definitions/auth_data.yaml"
description: |-
Additional authentication information for the
user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
required:
- devices
responses:

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

@ -119,7 +119,7 @@ paths:
responses:
200:
description: |-
"The filter defintion"
The filter definition.
examples:
application/json: {
"room": {

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

@ -31,7 +31,8 @@ paths:
post:
summary: Start the requesting user participating in a particular room.
description: |-
*Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
*Note that this API requires a room ID, not alias.*
``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
This API starts a user participating in a particular room, if that user
is allowed to participate in that room. After this call, the client is
@ -40,10 +41,6 @@ paths:
After a user has joined a room, the room will appear as an entry in the
response of the |/initialSync|_ and |/sync|_ APIs.
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
operationId: joinRoomById
security:
- accessToken: []
@ -56,11 +53,17 @@ paths:
x-example: "!d41d8cd:matrix.org"
- in: body
name: third_party_signed
required: true
schema:
type: object
properties:
third_party_signed:
$ref: "definitions/third_party_signed.yaml"
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If supplied, the homeserver must verify that it matches a pending
``m.room.third_party_invite`` event in the room, and perform
key validity checking if required by the event.
responses:
200:
description: |-
@ -79,7 +82,8 @@ paths:
required: ["room_id"]
403:
description: |-
You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
You do not have permission to join the room. A meaningful ``errcode``
and description error text will be returned. Example reasons for rejection are:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
@ -107,10 +111,6 @@ paths:
After a user has joined a room, the room will appear as an entry in the
response of the |/initialSync|_ and |/sync|_ APIs.
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
operationId: joinRoom
security:
- accessToken: []
@ -132,11 +132,17 @@ paths:
x-example: ["matrix.org", "elsewhere.ca"]
- in: body
name: third_party_signed
required: true
schema:
type: object
properties:
third_party_signed:
$ref: "definitions/third_party_signed.yaml"
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
responses:
200:
description: |-
@ -155,7 +161,8 @@ paths:
required: ["room_id"]
403:
description: |-
You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
You do not have permission to join the room. A meaningful ``errcode``
and description error text will be returned. Example reasons for rejection are:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.

5
api/client-server/key_backup.yaml
View file

@ -39,6 +39,7 @@ paths:
- in: body
name: version
description: "The backup configuration."
required: true
schema:
type: object
properties:
@ -257,6 +258,7 @@ paths:
- in: body
name: version
description: "The backup configuration"
required: true
schema:
type: object
properties:
@ -398,6 +400,7 @@ paths:
- in: body
name: data
description: "The key data."
required: true
schema:
"$ref": "definitions/key_backup_data.yaml"
responses:
@ -568,6 +571,7 @@ paths:
- in: body
description: "The backup data"
name: backupData
required: true
schema:
$ref: "definitions/room_key_backup.yaml"
responses:
@ -734,6 +738,7 @@ paths:
- in: body
description: "The backup data."
name: backupData
required: true
schema:
type: object
properties:

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

@ -41,6 +41,7 @@ paths:
name: keys
description: |-
The keys to be published
required: true
schema:
type: object
properties:
@ -133,6 +134,7 @@ paths:
name: query
description: |-
Query defining the keys to be downloaded
required: true
schema:
type: object
properties:
@ -196,6 +198,7 @@ paths:
additionalProperties:
type: object
additionalProperties:
title: DeviceInformation
allOf:
- $ref: definitions/device_keys.yaml
properties:
@ -249,6 +252,7 @@ paths:
name: query
description: |-
Query defining the keys to be claimed
required: true
schema:
type: object
properties:

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

@ -77,7 +77,8 @@ paths:
type: object
403:
description: |-
You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
You do not have permission to kick the user from the room. A meaningful ``errcode`` and
description error text will be returned. Example reasons for rejections are:
- The kicker is not currently in the room.
- The kickee is not currently in the room.

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

@ -82,6 +82,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
example: {
@ -99,7 +100,6 @@ paths:
enum: ["m.login.password", "m.login.token"]
description: The login type being used.
identifier:
description: Identification information for the user.
"$ref": "definitions/user_identifier.yaml"
user:
type: string
@ -175,13 +175,13 @@ paths:
ID of the logged-in device. Will be the same as the
corresponding parameter in the request, if one was specified.
well_known:
type: object
description: |-
Optional client configuration provided by the server. If present,
clients SHOULD use the provided object to reconfigure themselves,
optionally validating the URLs within. This object takes the same
form as the one returned from .well-known autodiscovery.
"$ref": "definitions/wellknown/full.yaml"
allOf:
- "$ref": "definitions/wellknown/full.yaml"
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.

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

@ -111,8 +111,6 @@ paths:
for ``dir=f`` in chronological order, so that events start
at the ``from`` point.
items:
type: object
title: RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: array
@ -126,8 +124,6 @@ paths:
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
type: object
title: RoomStateEvent
$ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples:
application/json: {

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

@ -49,7 +49,7 @@ paths:
name: limit
description: Limit on the number of events to return in this request.
required: false
x-example: "20"
x-example: 20
- in: query
name: only
type: string

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

@ -62,7 +62,7 @@ paths:
description: The new presence state.
status_msg:
type: string
description: "The status message to attach to this state."
description: The status message to attach to this state.
required: ["presence"]
responses:
200:

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

@ -45,7 +45,7 @@ paths:
x-example: "@alice:example.com"
- in: body
name: displayName
description: The display name info.
description: The new display name information.
required: true
schema:
type: object
@ -119,7 +119,7 @@ paths:
x-example: "@alice:example.com"
- in: body
name: avatar_url
description: The avatar url info.
description: The new avatar information.
required: true
schema:
type: object

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

@ -65,6 +65,7 @@ paths:
x-example: "37"
- in: body
name: body
required: true
schema:
type: object
example: {

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

@ -84,6 +84,7 @@ paths:
description: The kind of account to register. Defaults to ``user``.
- in: body
name: body
required: true
schema:
type: object
properties:
@ -94,7 +95,8 @@ paths:
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself.
"$ref": "definitions/auth_data.yaml"
allOf:
- "$ref": "definitions/auth_data.yaml"
username:
type: string
description: |-
@ -227,7 +229,7 @@ paths:
name: body
required: true
schema:
$ref: "./definitions/request_email_validation.yaml"
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: |-
@ -277,7 +279,7 @@ paths:
name: body
required: true
schema:
$ref: "./definitions/request_msisdn_validation.yaml"
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: |-
@ -336,6 +338,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -355,7 +358,8 @@ paths:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
allOf:
- "$ref": "definitions/auth_data.yaml"
required: ["new_password"]
responses:
200:
@ -404,7 +408,7 @@ paths:
name: body
required: true
schema:
$ref: "./definitions/request_email_validation.yaml"
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: An email was sent to the given address.
@ -462,7 +466,7 @@ paths:
name: body
required: true
schema:
$ref: "../identity/definitions/request_msisdn_validation.yaml"
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
@ -516,13 +520,15 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
allOf:
- $ref: "definitions/auth_data.yaml"
id_server:
type: string
description: |-

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

@ -45,7 +45,6 @@ paths:
- in: body
name: body
required: true
description: The request body
schema:
type: object
properties:

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

@ -45,6 +45,7 @@ paths:
x-example: "YWxsCgpOb25lLDM1ODcwOA"
- in: body
name: body
required: true
schema:
type: object
example: {
@ -95,7 +96,8 @@ paths:
# for now :/
description: |-
This takes a `filter`_.
$ref: "definitions/room_event_filter.yaml"
allOf:
- $ref: "definitions/room_event_filter.yaml"
order_by:
title: "Ordering"
type: string

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

@ -39,7 +39,6 @@ paths:
200:
description: Server discovery information.
schema:
type: object
"$ref": "definitions/wellknown/full.yaml"
404:
description: No server discovery information available.

13
api/openapi_extensions.md
View file

@ -6,6 +6,19 @@ across the specification. The defined extensions are listed below. Extensions
should not break parsers, however if extra functionality is required, aware
parsers should be able to take advantage of the added syntax.
## Using multiple files to describe API
To ease API design and management, the API definition is split across several
files. Each of these files is self-contained valid OpenAPI (except
client-server files that become valid OpenAPI after substituting
`%CLIENT_MAJOR_VERSION%` with `unstable` or an API release).
There is no single root file in the source tree as OpenAPI requires; this file
can be generated by `dump_swagger.py` (also doing the substitution mentioned
above). The script does not convert the extensions described further in this
document (`oneOf` and parameter exploding) so there can be minor
interoperability issues with tooling that expects compliant Swagger.
## Extensible Query Parameters
<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->

2
api/server-server/public_rooms.yaml
View file

@ -86,7 +86,7 @@ paths:
name: body
required: true
description: |-
Options for which rooms to return.
Options for which rooms to return, or empty object to use defaults.
schema:
type: object
properties:

2
scripts/dump-swagger.py
View file

@ -43,7 +43,7 @@ parser = argparse.ArgumentParser(
parser.add_argument(
"--client_release", "-c", metavar="LABEL",
default="unstable",
help="""The client-server release version to gneerate for. Default:
help="""The client-server release version to generate for. Default:
%(default)s""",
)
parser.add_argument(