diff --git a/drafts/as-http-api.rst b/drafts/as-http-api.rst index 826a774d..d7c749f9 100644 --- a/drafts/as-http-api.rst +++ b/drafts/as-http-api.rst @@ -10,6 +10,9 @@ This contains home server APIs which are used by the application service. Registration API ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. NOTE:: + - Do we really have to use regex for this? Can't we do this a nicer way? + This API registers the application service with its host homeserver to offer its services. Inputs: @@ -19,38 +22,18 @@ Inputs: - 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"] - } + - Namespaces are represented by POSIX extended regular expressions in JSON. + They look like:: + users: [ + "irc\.freenode\.net/.*", + ] 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 @@ -60,15 +43,12 @@ Notes: url: "https://my.application.service.com/matrix/", as_token: "some_AS_token", namespaces: { - users: { - irc: ["freenode", "rizon"] - }, - rooms: { - irc: { - freenode: ["matrix"], - rizon: ["matrixorg"] - } - } + users: [ + "irc\.freenode\.net/.*" + ], + rooms: [ + "irc\.freenode\.net/.*" + ] } } @@ -83,18 +63,7 @@ Notes: 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"] - } - } - } + hs_token: "foobar" } Unregister API ``[TODO]`` @@ -108,6 +77,10 @@ This contains application service APIs which are used by the home server. User Query ``[Draft]`` ~~~~~~~~~~~~~~~~~~~~~~ +.. NOTE:: + - This API may be called a lot by the HS (e.g. incoming events for unknown user IDs, profile + requests, etc. Is this okay? + This API is called by the HS to query the existence of a user on the Application Service's namespace. Inputs: