archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Specify how capabilities work in the c2s API

Browse Source 
Original proposals:
* https://github.com/matrix-org/matrix-doc/pull/1753
* https://github.com/matrix-org/matrix-doc/pull/1804

Implementation proof:
* https://github.com/matrix-org/synapse/pull/4472
* https://github.com/matrix-org/matrix-js-sdk/pull/830

There is one change to MSC1753 which is included in this commit. MSC1804 remains unchanged. In the original proposal, the change password capability being present was an indication that password changes were possible. It was found that this doesn't really communicate the state very well to clients in that lack of a capability (or a 404, etc) would mean that users would erroneously not be able to change their passwords. A simple boolean flag was added to assist clients in detecting this capability.
pull/977/head
Travis Ralston 6 years ago
parent 72a2871021
commit ccce6c196d
4 changed files with 214 additions and 2 deletions
Show Stats Download Patch File Download Diff File

108
api/client-server/capabilities.yaml
Unescape Escape View File

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

1
changelogs/client_server/newsfragments/1829.feature
Unescape Escape View File

@ -0,0 +1 @@
Support optional features by having clients query for capabilities.

6
proposals/1753-capabilities.md
Unescape Escape View File

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

101
specification/client_server_api.rst
Unescape Escape View File

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

Write Preview
Loading…
Cancel
Save