matrix-spec-proposals/proposals/1753-capabilities.md

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

GET /_matrix/client/r0/capabilities

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.

The server should reply with a list of supported features, as shown:

{
    "capabilities": {
        "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 be the empty object.

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).

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) - 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.

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.