# 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 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
      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