MSC1753: client-server capabilities API
parent
e30543a3fe
commit
0e156faaf1
@ -0,0 +1,99 @@
|
||||
# MSC1753: client-server capabilities API
|
||||
|
||||
A mechanism is needed for clients to interrogate servers to establish whether
|
||||
particular operations can be performed.
|
||||
|
||||
For example, users may not be able to change their password if a server is
|
||||
configured to authenticate against a separate system, in which case it is
|
||||
nonsensical to offer the user such an option.
|
||||
|
||||
## Proposal
|
||||
|
||||
### `POST /_matrix/client/r0/capabilities`
|
||||
|
||||
We will add a new endpoint to the client-server API: `POST
|
||||
/_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:
|
||||
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"m.capability_one": {},
|
||||
"com.example.custom_capability": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The keys of the `capabilities` object are capability identifiers. As with
|
||||
other identifiers in the Matrix protocol, the `m.` prefix is reserved for
|
||||
definition in the Matrix specification; other values can be used within an
|
||||
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:
|
||||
`m.change_password`, which should be considered supported if it is possible to
|
||||
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.
|
||||
|
||||
### Fallback behaviour
|
||||
|
||||
Clients will need to be aware of servers which do not support the new endpoint,
|
||||
and fall back to their current behaviour if they receive a 404 response.
|
||||
|
||||
## Tradeoffs
|
||||
|
||||
One alternative would be to provide specific ways of establishing support for
|
||||
each operation: for example, a client might send an `GET
|
||||
/_matrix/client/r0/account/password` request to see if the user can change
|
||||
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.
|
||||
|
||||
## Potential issues
|
||||
|
||||
None yet identified.
|
||||
|
||||
## Security considerations
|
||||
|
||||
None yet identified.
|
||||
|
||||
## Conclusion
|
||||
|
||||
We propose adding a new endpoint to the Client-Server API, which will allow
|
||||
clients to query for supported operations so that they can decide whether to
|
||||
expose them in their user-interface.
|
Loading…
Reference in New Issue