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 ## 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 /_matrix/client/r0/capabilities`. The endpoint will be authenticated as normal
via an access token. via an access token.
The body of the request will list the capabilities the client is interested The server should reply with a list of supported features, as shown:
in, as shown:
```json ```json
{ {
"capabilities": { "capabilities": {
"m.capability_one": {}, "m.capability_one": {}
"com.example.custom_capability": {}
} }
} }
``` ```
@ -35,25 +33,6 @@ organisation following the Java package naming conventions.
The values of the `capabilities` object will depend on the capability The values of the `capabilities` object will depend on the capability
identifier, though in general the empty object will suffice. 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 ### Initial capability identifiers
As a starting point, a single capability identifier is proposed: 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` change the user's password via the `POST /_matrix/client/r0/account/password`
API. API.
The values of the `capabilities` object should be the empty object in both the The value of the `capabilities` object in the response should be the empty
query and the response. object.
### Fallback behaviour ### Fallback behaviour
@ -93,7 +72,6 @@ Examples of features which might reasonably be advertised here include:
* The number of rooms you are allowed in. * The number of rooms you are allowed in.
* Configured ratelimits. * Configured ratelimits.
Features which might be better advertised elsewhere include: Features which might be better advertised elsewhere include:
* Support for e2e key backups * 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 * Variations in room state resolution - this is implied via the room version
(which is in the `m.room.create` event). (which is in the `m.room.create` event).
## Tradeoffs ## Tradeoffs
One alternative would be to provide specific ways of establishing support for 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 large number of requests to establish which entries should appear on a menu or
dialog box. dialog box.
Another alternative would be a simple `GET /_matrix/client/r0/capabilities` Another alternative is to provide a generic query mechanism where the client
query, where a server would return all possible supported operations. The can query for specific capabilities it is interested in. However, this adds
problem with this is that it may add load to the server, and increase network complication and makes it harder to discover capability identifiers.
traffic, by returning a large number of features which the client may have no
interest in.
## Potential issues ## Potential issues