Draft Registration and User Query APIs

drafts/as-http-api.rst

@@ -0,0 +1,140 @@
+Application Services HTTP API
+=============================
+
+.. contents:: Table of Contents
+.. sectnum::
+
+Application Service -> Home Server
+----------------------------------
+This contains home server APIs which are used by the application service.
+
+Registration API ``[Draft]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This API registers the application service with its host homeserver to offer its services.
+
+Inputs:
+ - Credentials (e.g. some kind of string token)
+ - Namespace[users]
+ - Namespace[room aliases]
+ - URL base to receive inbound comms
+Output:
+ - The credentials the HS will use to query the AS with in return. (e.g. some kind of string token)
+ - The complete namespace prefix for each namespace requested.
+Side effects:
+ - The HS will start delivering events to the URL base specified if this 200s.
+API called when:
+ - The application service wants to register with a brand new home server.
+Notes:
+ - Namespaces are represented in JSON, with a well-defined conversion to IDs. This prevents
+   parsing errors and allows the HS to enforce their own namespacing semantics. They look like::
+     users: {
+       irc: ["freenode", "rizon"]
+     }
+   which represents 2 namespaces: ``@.irc.freenode.*`` and ``@.irc.rizon.*``. The leaf nodes
+   must be an array. Intermediate nodes must be JSON objects with the key as the desired string
+   segment. A more complicated example::
+     rooms: {
+       irc: {
+         freenode: ["matrix"],
+         rizon: ["matrixorg"]
+       }
+     }
+   which represents 2 namespaces: ``#.irc.freenode.matrix.*`` and ``#.irc.rizon.matrixorg.*``.
+ - By specifying namespaces like this, you allow home servers to namespace application services
+   sensibly, rather than every IRC AS trying to nab all ``@.irc.*`` users. In order for home
+   servers to do this, they need to tell the application service the actual namespaces allocated
+   for them. This is returned in the JSON response, with the same structure as the original request,
+   but with the strings now representing the namespace prefix allocated, e.g::
+     users: {
+       irc: [".applicationservice_146.irc.freenode", ".applicationservice_146.irc.rizon"]
+     }
+   The sigil prefix ``@`` is omitted since it is clear from the ``users`` key that these namespace
+   prefixes are for users.
+ - This makes the request/response JSON structure deliciously symmetric.
+::
+
+ POST /register
+ 
+ Request format
+ {
+   url: "https://my.application.service.com/matrix/",
+   as_token: "some_AS_token",
+   namespaces: {
+     users: {
+       irc: ["freenode", "rizon"]
+     },
+     rooms: {
+       irc: {
+         freenode: ["matrix"],
+         rizon: ["matrixorg"]
+       }
+     }
+   }
+ }
+ 
+ 
+ Returns:
+   200 : Registration accepted.
+   400 : Namespaces do not conform to regex
+   401 : Credentials need to be supplied.
+   403 : AS credentials rejected.
+ 
+ 
+   200 OK response format
+ 
+   {
+     hs_token: "foobar",
+     namespaces: {
+       users: {
+         irc: [".applicationservice_146.irc.freenode", ".applicationservice_146.irc.rizon"]
+       },
+       rooms: {
+         irc: {
+           freenode: [".irc.freenode.matrix"],
+           rizon: [".applicationservice_146.this.can.be.any.prefix.you.like"]
+         }
+       }
+     }
+   }
+
+
+Home Server -> Application Service
+----------------------------------
+This contains application service APIs which are used by the home server.
+
+User Query ``[Draft]``
+~~~~~~~~~~~~~~~~~~~~~~
+This API is called by the HS to query the existence of a user on the Application Service's namespace.
+
+Inputs:
+ - User ID
+ - HS Credentials
+Output:
+ - Profile info
+Side effects:
+ - User is created on the HS if this response 200s.
+API called when:
+ - HS receives an event for an unknown user ID in the AS's namespace.
+Notes:
+ - The created user will have their profile info set based on the output.
+ 
+::
+
+ GET /users/$user_id?access_token=$hs_token
+ 
+ Returns:
+   200 : User is recognised.
+   404 : User not found.
+   401 : Credentials need to be supplied.
+   403 : HS credentials rejected.
+ 
+ 
+   200 OK response format
+ 
+   {
+     profile: {
+       display_name: "Foo"
+       avatar_url: "mxc://foo/bar"
+     }
+   }
+