You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/data/api/client-server/versions.yaml

109 lines
4.2 KiB
YAML

# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
title: Matrix Client-Server Versions API
version: 1.0.0
paths:
/versions:
get:
summary: Gets the versions of the specification supported by the server.
description: |-
Gets the versions of the specification supported by the server.
Values will take the form `vX.Y` or `rX.Y.Z` in historical cases. See
[the Specification Versioning](../#specification-versions) for more
information.
The server may additionally advertise experimental features it supports
through `unstable_features`. These features should be namespaced and
may optionally include version information within their name if desired.
Features listed here are not for optionally toggling parts of the Matrix
specification and should only be used to advertise support for a feature
which has not yet landed in the spec. For example, a feature currently
undergoing the proposal process may appear here and eventually be taken
off this list once the feature lands in the spec and the server deems it
reasonable to do so. Servers can choose to enable some features only for
some users, so clients should include authentication in the request to
get all the features available for the logged-in user. If no
authentication is provided, the server should only return the features
available to all users. Servers may wish to keep advertising features
here after they've been released into the spec to give clients a chance
to upgrade appropriately. Additionally, clients should avoid using
unstable features in their stable releases.
operationId: getVersions
security:
- {}
- accessTokenQuery: []
- accessTokenBearer: []
x-changedInMatrixVersion:
"1.10": |
This endpoint can behave differently when authentication is provided.
responses:
"200":
description: The versions supported by the server.
content:
application/json:
schema:
type: object
properties:
versions:
type: array
description: The supported versions.
items:
type: string
description: The supported versions
unstable_features:
type: object
description: |-
Experimental features the server supports. Features not listed here,
or the lack of this property all together, indicate that a feature is
not supported.
additionalProperties:
type: boolean
description: Whether or not the namespaced feature is supported.
required:
- versions
examples:
response:
value: {
"versions": [
"r0.0.1",
"v1.1"
],
"unstable_features": {
"org.example.my_feature": true
}
}
tags:
- Server administration
servers:
- url: "{protocol}://{hostname}{basePath}"
variables:
protocol:
enum:
- http
- https
default: https
hostname:
default: localhost:8008
basePath:
default: /_matrix/client
components:
securitySchemes:
accessTokenQuery:
$ref: definitions/security.yaml#/accessTokenQuery
accessTokenBearer:
$ref: definitions/security.yaml#/accessTokenBearer