switch to GET

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