From 0e156faaf1c67d1f45345f45ac837f87ca8d74ba Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Wed, 12 Dec 2018 21:43:40 +0000
Subject: [PATCH] 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 00000000..23d22c4f
--- /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.