wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

switch to GET

Browse source
This commit is contained in:
Richard van der Hoff 2018-12-21 17:47:52 +00:00
parent 68ac2172ba
commit 82f3b8a95a
1 changed files with 9 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

43
proposals/1753-capabilities.md
View file

@ -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