From 9af912eba506c754505498027b736a514e953454 Mon Sep 17 00:00:00 2001
From: Kegsay <kegsay@gmail.com>
Date: Wed, 31 Dec 2014 16:05:24 +0000
Subject: [PATCH] Add capability API

---
 drafts/general_api.rst | 57 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/drafts/general_api.rst b/drafts/general_api.rst
index cb005b007..511d27a6a 100644
--- a/drafts/general_api.rst
+++ b/drafts/general_api.rst
@@ -415,7 +415,64 @@ Events (breaking changes; event version 2)
 - Do we want to specify what restrictions apply to the state key in the event type? This would allow HSes
   to enforce this, making life easier for clients when dealing with custom event types. E.g. ``_custom.event``
   would allow anything in the state key, ``_@custom.event`` would only allow user IDs in the state key, etc.
+- s/user_id/sender/g given that home servers can send events, not just users.
 
+Capabilities
+------------
+How does a client know if the server it is using supports a content repository? How does a client know 
+if another client has VoIP support? This section outlines capability publishing for servers,
+clients and federation.
+
+Server
+~~~~~~
+- List of extensions it supports (e.g. content repo, contact repo, turn servers)
+
+Inputs:
+ - User ID (e.g. only @bob can use the content repo)
+Output:
+ - Hash of the capabilities::
+ 
+    {
+      "sha256": "fD876SFrt3sugh23FWEjio3"
+    }
+
+This hash is fed into another API:
+
+Inputs:
+ - The hash of the capabilities
+Output:
+ - A list of capabilities::
+ 
+    {
+      "custom.feature.v1": {},
+      "m.cap.turnserver.v1": {}
+    }
+
+Client
+~~~~~~
+- e.g. Whether this client supports VoIP
+
+When a session is started, the client needs to provide a capability set. The server will take the "union"
+of all the user's connected clients' capability sets and send the hash of the capabilities as part of 
+presence information (not necesarily as a ``m.presence`` event, but it should act like presence events).
+
+On first signup, the client will attempt to send the hash and be most likely refused by the home server as
+it does not know the full capability set for that hash. The client will then have to upload the full capability
+set to the home server. The client will then be able to send the hash as normal.
+
+When a client receives a hash, the client will either recognise the hash or will have to request the capability
+set from their home server:
+
+Inputs:
+ - Hash
+ - User ID
+Output:
+ - A list of capabilities
+
+Federation
+~~~~~~~~~~
+- e.g. Whether you support backfill, hypothetical search/query/threading APIs
+- Same as the server capability API
 
 VoIP
 ----