switch to GET
@@ -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
