diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index bcc5b2a3..386e66dc 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -9,20 +9,18 @@ nonsensical to offer the user such an option. ## Proposal -### `POST /_matrix/client/r0/capabilities` +### `GET /_matrix/client/r0/capabilities` -We will add a new endpoint to the client-server API: `POST +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 body of the request will list the capabilities the client is interested -in, as shown: +The server should reply with a list of supported features, as shown: ```json { "capabilities": { - "m.capability_one": {}, - "com.example.custom_capability": {} + "m.capability_one": {} } } ``` @@ -35,25 +33,6 @@ 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. -The server should reply with a list of the operations the client may perform, -as shown: - -```json -{ - "capabilities": { - "m.capability_one": {} - } -} -``` - -The server should exclude from the list any operations which the client cannot -currently perform. It should also exclude any capabilities it does not -recognise or support, or whose value in the query did not have the expected -form. - -Again the values of the `capabilities` object will depend on the capability -identifier. - ### Initial capability identifiers As a starting point, a single capability identifier is proposed: @@ -61,8 +40,8 @@ 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 values of the `capabilities` object should be the empty object in both the -query and the response. +The value of the `capabilities` object in the response should be the empty +object. ### Fallback behaviour @@ -93,7 +72,6 @@ Examples of features which might reasonably be advertised here include: * The number of rooms you are allowed in. * Configured ratelimits. - Features which might be better advertised elsewhere include: * Support for e2e key backups @@ -111,7 +89,6 @@ Features which might be better advertised elsewhere include: * 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 @@ -121,11 +98,9 @@ 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 would be a simple `GET /_matrix/client/r0/capabilities` -query, where a server would return all possible supported operations. The -problem with this is that it may add load to the server, and increase network -traffic, by returning a large number of features which the client may have no -interest in. +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