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/proposals/1753-capabilities.md

120 lines
4.1 KiB
Markdown

# MSC1753: client-server capabilities API
A mechanism is needed for clients to interrogate servers to establish whether
particular operations can be performed.
For example, users may not be able to change their password if a server is
configured to authenticate against a separate system, in which case it is
nonsensical to offer the user such an option.
## Proposal
6 years ago
### `GET /_matrix/client/r0/capabilities`
6 years ago
We will add a new endpoint to the client-server API: `GET
/_matrix/client/r0/capabilities`. The endpoint will be authenticated as normal
via an access token.
6 years ago
The server should reply with a list of supported features, as shown:
```json
{
"capabilities": {
6 years ago
"m.capability_one": {}
}
}
```
The keys of the `capabilities` object are capability identifiers. As with
other identifiers in the Matrix protocol, the `m.` prefix is reserved for
definition in the Matrix specification; other values can be used within an
organisation following the Java package naming conventions.
The values of the `capabilities` object will depend on the capability
identifier, though in general the empty object will suffice.
### Initial capability identifiers
As a starting point, a single capability identifier is proposed:
`m.change_password`, which should be considered supported if it is possible to
change the user's password via the `POST /_matrix/client/r0/account/password`
API.
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
Clients will need to be aware of servers which do not support the new endpoint,
and fall back to their current behaviour if they receive a 404 response.
### Suitable applications
In general, capabilities advertised via this endpoint should depend in some way
on the state of the user or server - in other words, they will be inherently
"optional" features in the API.
This endpoint should *not* be used to advertise support for experimental or
unstable features, which is better done via `/client/versions` (see
[MSC1497](https://github.com/matrix-org/matrix-doc/issues/1497)).
Examples of features which might reasonably be advertised here include:
* Whether the server supports user presence.
* Whether the server supports other optional features. The following could be
made optional via this mechanism:
* Room directory
* URL previews
* Policy restricitions, such as:
* Whether certain types of content are permitted on this server.
* The number of rooms you are allowed in.
* Configured ratelimits.
Features which might be better advertised elsewhere include:
* Support for e2e key backups
([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in
`/client/versions`.
* Support for lazy-loading of room members - list in `/client/versions`.
* Media size limits - list in `/media/r0/config`, because the media server may
be a separate process.
* Optional transports/encodings for the CS API - probably better handled via
HTTP headers etc.
* Variations in room state resolution - this is implied via the room version
(which is in the `m.room.create` event).
## Tradeoffs
One alternative would be to provide specific ways of establishing support for
each operation: for example, a client might send an `GET
/_matrix/client/r0/account/password` request to see if the user can change
their password. The concern with this approach is that this could require a
large number of requests to establish which entries should appear on a menu or
dialog box.
6 years ago
Another alternative is to provide a generic query mechanism where the client
can query for specific capabilities it is interested in. However, this adds
complication and makes it harder to discover capability identifiers.
## Potential issues
None yet identified.
## Security considerations
None yet identified.
## Conclusion
We propose adding a new endpoint to the Client-Server API, which will allow
clients to query for supported operations so that they can decide whether to
expose them in their user-interface.