From 0e156faaf1c67d1f45345f45ac837f87ca8d74ba Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 12 Dec 2018 21:43:40 +0000 Subject: [PATCH 1/7] MSC1753: client-server capabilities API --- proposals/1753-capabilities.md | 99 ++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 proposals/1753-capabilities.md diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md new file mode 100644 index 00000000000..23d22c4f97b --- /dev/null +++ b/proposals/1753-capabilities.md @@ -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. From 68ac2172bab4669cf5243c241b606c0ff254acdb Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 21 Dec 2018 17:39:52 +0000 Subject: [PATCH 2/7] Give examples of applications --- proposals/1753-capabilities.md | 43 ++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 23d22c4f97b..bcc5b2a3147 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -69,6 +69,49 @@ query and the response. 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. +### Suitable applications + +In general, capabilities advertised via this endpoiunt should depend in some +way on the state of the user or server - in other words, they will inherently +"optional" features in the API. + +This endpoint should *not* be used to advertise support for experimental or +unstable features, which is better done via `/client/r0/versions` (see +[MSC1497](https://github.com/matrix-org/matrix-doc/issues/1497)). + +Examples of features which might reasonably be advertised here include: + + * Whether the server supports user presence. + + * Whether the server supports other optional features. The following could be + made optional via this mechanism: + * Room directory + * URL previews + + * Policy restricitions, such as: + * Whether certain types of content are permitted on this server. + * The number of rooms you are allowed in. + * Configured ratelimits. + + +Features which might be better advertised elsewhere include: + + * Support for e2e key backups + ([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in + `/client/r0/versions`. + + * Support for lazy-loading of room members - list in `/client/r0/versions`. + + * Media size limits - list in `/media/r0/config`, because the media server may + be a separate process. + + * Optional transports/encodings for the CS API - probably better handled via + HTTP headers etc. + + * 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 From 82f3b8a95a4be1b485a23be775458aea53ba324e Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 21 Dec 2018 17:47:52 +0000 Subject: [PATCH 3/7] switch to GET --- proposals/1753-capabilities.md | 43 +++++++--------------------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index bcc5b2a3147..386e66dc084 100644 --- a/proposals/1753-capabilities.md +++ b/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 From 7f5832044c6b16d1099dc117bea481ed7613f338 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 2 Jan 2019 09:55:14 +0000 Subject: [PATCH 4/7] Fix typos per review --- proposals/1753-capabilities.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 386e66dc084..4ac0ac05afa 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -50,8 +50,8 @@ and fall back to their current behaviour if they receive a 404 response. ### Suitable applications -In general, capabilities advertised via this endpoiunt should depend in some -way on the state of the user or server - in other words, they will inherently +In general, capabilities advertised via this endpoint should depend in some way +on the state of the user or server - in other words, they will be inherently "optional" features in the API. This endpoint should *not* be used to advertise support for experimental or From 962565b15959b032eb38943ad57ff577d5e03cd2 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Jan 2019 17:40:49 +0000 Subject: [PATCH 5/7] Update proposals/1753-capabilities.md r0/versions isn't a thing Co-Authored-By: richvdh <1389908+richvdh@users.noreply.github.com> --- proposals/1753-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 4ac0ac05afa..5c3ada4107b 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -55,7 +55,7 @@ on the state of the user or server - in other words, they will be inherently "optional" features in the API. This endpoint should *not* be used to advertise support for experimental or -unstable features, which is better done via `/client/r0/versions` (see +unstable features, which is better done via `/client/versions` (see [MSC1497](https://github.com/matrix-org/matrix-doc/issues/1497)). Examples of features which might reasonably be advertised here include: From 40196786619f75f3424258735f3958ac69b6a455 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Jan 2019 17:40:57 +0000 Subject: [PATCH 6/7] Update proposals/1753-capabilities.md r0/versions isn't a thing Co-Authored-By: richvdh <1389908+richvdh@users.noreply.github.com> --- proposals/1753-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index 5c3ada4107b..cbda92d85f3 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -76,7 +76,7 @@ Features which might be better advertised elsewhere include: * Support for e2e key backups ([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in - `/client/r0/versions`. + `/client/versions`. * Support for lazy-loading of room members - list in `/client/r0/versions`. From ca2e9260d427b9ec620e7fa94c9d13345cda463e Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 3 Jan 2019 17:41:06 +0000 Subject: [PATCH 7/7] Update proposals/1753-capabilities.md r0/versions isn't a thing Co-Authored-By: richvdh <1389908+richvdh@users.noreply.github.com> --- proposals/1753-capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/1753-capabilities.md b/proposals/1753-capabilities.md index cbda92d85f3..ec5169aba0f 100644 --- a/proposals/1753-capabilities.md +++ b/proposals/1753-capabilities.md @@ -78,7 +78,7 @@ Features which might be better advertised elsewhere include: ([MSC1219](https://github.com/matrix-org/matrix-doc/issues/1219)) - list in `/client/versions`. - * Support for lazy-loading of room members - list in `/client/r0/versions`. + * Support for lazy-loading of room members - list in `/client/versions`. * Media size limits - list in `/media/r0/config`, because the media server may be a separate process.