diff --git a/api/client-server/capabilities.yaml b/api/client-server/capabilities.yaml new file mode 100644 index 00000000..acec600d --- /dev/null +++ b/api/client-server/capabilities.yaml @@ -0,0 +1,108 @@ +# Copyright 2019 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 Capabiltiies API" + version: "1.0.0" +host: localhost:8008 +schemes: + - https + - http +basePath: /_matrix/client/%CLIENT_MAJOR_VERSION% +produces: + - application/json +securityDefinitions: + $ref: definitions/security.yaml +paths: + "/capabilities": + get: + summary: Gets information about the server's capabilities. + description: |- + Gets information about the server's supported feature set + and other relevant capabilities. + operationId: getCapabilities + security: + - accessToken: [] + parameters: [] + responses: + 200: + description: + The capabilities of the server + examples: + application/json: { + "capabilities": { + "m.change_password": { + "enabled": false + }, + "m.room_versions": { + "default": "1", + "available": { + "1": "stable", + "2": "stable", + "3": "unstable", + "test-version": "unstable" + } + }, + "com.example.custom.ratelimit": { + "max_requests_per_hour": 600 + } + } + } + schema: + type: object + required: ["capabilities"] + additionalProperties: + type: object + description: |- + The custom capabilities the server supports, using the + Java package naming convention. + properties: + "m.change_password": + type: object + description: |- + Capability to indicate if the user can change their password. + title: ChangePasswordCapability + properties: + enabled: + type: boolean + description: |- + True if the user can change their password, false otherwise. + example: false + required: ['enabled'] + "m.room_versions": + type: object + description: The room versions the server supports. + title: RoomVersionsCapability + properties: + default: + type: string + description: |- + The default room version the server is using for new rooms. + example: "1" + available: + type: object + description: |- + A detailed description of the room versions the server supports. + additionalProperties: + type: string + title: RoomVersionStability + enum: [stable, unstable] + description: The stability of the room version. + required: ['default', 'available'] + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/errors/rate_limited.yaml" + tags: + - Capabilities diff --git a/changelogs/client_server/newsfragments/1829.feature b/changelogs/client_server/newsfragments/1829.feature new file mode 100644 index 00000000..107291f3 --- /dev/null +++ b/changelogs/client_server/newsfragments/1829.feature @@ -0,0 +1 @@ +Support optional features by having clients query for capabilities. diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index ec5169ab..5a56eaca 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -40,8 +40,10 @@ As a starting point, a single capability identifier is proposed: change the user's password via the `POST /_matrix/client/r0/account/password` API. -The value of the `capabilities` object in the response should be the empty -object. +The value of the `capabilities` object in the response should contain a single +boolean flag, `enabled`, to indicate whether a password change is possible. If +the capability is not listed, the client should assume that password changes +are possible. ### Fallback behaviour diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index 4df83814..40ac5588 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -1070,6 +1070,107 @@ Current account information {{whoami_cs_http_api}} +Capabilities negotiation +------------------------ + +A homeserver may not support certain operations and clients must be able to +query for what the homeserver can and can't offer. For example, a homeserver +may not support users changing their password as it is configured to perform +authentication against an external system. + +The capabilities advertised through this system are intended to advertise +functionality which is optional in the API, or which depend in some way on +the state of the user or server. This system should not be used to advertise +unstable or experimental features - this is better done by the ``/versions`` +endpoint. + +Some examples of what a reasonable capability could be are: + +* Whether the server supports user presence. + +* Whether the server supports optional features, such as the user or room + directories. + +* The rate limits or file type restrictions imposed on clients by the server. + +Some examples of what should **not** be a capability are: + +* Whether the server supports a feature in the ``unstable`` specification. + +* Media size limits - these are handled by the ``/media/%CLIENT_MAJOR_VERSION%/config`` + API. + +* Optional encodings or alternative transports for communicating with the + server. + +Capabilities prefixed with ``m.`` are reserved for definition in the Matrix +specification while other values may be used by servers using the Java package +naming convention. The capabilities supported by the Matrix specification are +defined later in this section. + +{{capabilities_cs_http_api}} + + +``m.change_password`` capability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This capability has a single flag, ``enabled``, which indicates whether or not +the user can use the ``/account/password`` API to change their password. If not +present, the client should assume that password changes are possible via the +API. When present, clients SHOULD respect the capability's ``enabled`` flag +and indicate to the user if they are unable to change their password. + +An example of the capability API's response for this capability is:: + + { + "capabilities": { + "m.change_password": { + "enabled": false + } + } + } + + +``m.room_versions`` capability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This capability describes the default and available room versions a server +supports, and at what level of stability. Clients should make use of this +capability to determine if users need to be encouraged to upgrade their rooms. + +An example of the capability API's response for this capability is:: + + { + "capabilities": { + "m.room_versions": { + "default": "1", + "available": { + "1": "stable", + "2": "stable", + "3": "unstable", + "custom-version": "unstable" + } + } + } + } + +This capability mirrors the same restrictions of `room versions`_ to describe +which versions are stable and unstable. Clients should assume that the ``default`` +version is ``stable``. Any version not explicitly labelled as ``stable`` in the +``available`` versions is to be treated as ``unstable``. For example, a version +listed as ``future-stable`` should be treated as ``unstable``. + +The ``default`` version is the version the server is using to create new rooms. +Clients should encourage users with sufficient permissions in a room to upgrade +their room to the ``default`` version when the room is using an ``unstable`` +version. + +When this capability is not listed, clients should use ``"1"`` as the default +and only stable ``available`` room version. + +.. _`room versions`: ../index.html#room-versions + + Pagination ----------