Modify Register API
As per https://github.com/matrix-org/matrix-doc/pull/5#issuecomment-70059200
This commit is contained in:
parent
cdeb0faf85
commit
d8cd4a45d4
1 changed files with 19 additions and 46 deletions
|
@ -10,6 +10,9 @@ This contains home server APIs which are used by the application service.
|
||||||
|
|
||||||
Registration API ``[Draft]``
|
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.
|
This API registers the application service with its host homeserver to offer its services.
|
||||||
|
|
||||||
Inputs:
|
Inputs:
|
||||||
|
@ -19,38 +22,18 @@ Inputs:
|
||||||
- URL base to receive inbound comms
|
- URL base to receive inbound comms
|
||||||
Output:
|
Output:
|
||||||
- The credentials the HS will use to query the AS with in return. (e.g. some kind of string token)
|
- 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:
|
Side effects:
|
||||||
- The HS will start delivering events to the URL base specified if this 200s.
|
- The HS will start delivering events to the URL base specified if this 200s.
|
||||||
API called when:
|
API called when:
|
||||||
- The application service wants to register with a brand new home server.
|
- The application service wants to register with a brand new home server.
|
||||||
Notes:
|
Notes:
|
||||||
- Namespaces are represented in JSON, with a well-defined conversion to IDs. This prevents
|
- Namespaces are represented by POSIX extended regular expressions in JSON.
|
||||||
parsing errors and allows the HS to enforce their own namespacing semantics. They look like::
|
They look like::
|
||||||
users: {
|
users: [
|
||||||
irc: ["freenode", "rizon"]
|
"irc\.freenode\.net/.*",
|
||||||
}
|
]
|
||||||
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
|
The sigil prefix ``@`` is omitted since it is clear from the ``users`` key that these namespace
|
||||||
prefixes are for users.
|
prefixes are for users.
|
||||||
- This makes the request/response JSON structure deliciously symmetric.
|
|
||||||
::
|
::
|
||||||
|
|
||||||
POST /register
|
POST /register
|
||||||
|
@ -60,15 +43,12 @@ Notes:
|
||||||
url: "https://my.application.service.com/matrix/",
|
url: "https://my.application.service.com/matrix/",
|
||||||
as_token: "some_AS_token",
|
as_token: "some_AS_token",
|
||||||
namespaces: {
|
namespaces: {
|
||||||
users: {
|
users: [
|
||||||
irc: ["freenode", "rizon"]
|
"irc\.freenode\.net/.*"
|
||||||
},
|
],
|
||||||
rooms: {
|
rooms: [
|
||||||
irc: {
|
"irc\.freenode\.net/.*"
|
||||||
freenode: ["matrix"],
|
]
|
||||||
rizon: ["matrixorg"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -83,18 +63,7 @@ Notes:
|
||||||
200 OK response format
|
200 OK response format
|
||||||
|
|
||||||
{
|
{
|
||||||
hs_token: "foobar",
|
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"]
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
Unregister API ``[TODO]``
|
Unregister API ``[TODO]``
|
||||||
|
@ -108,6 +77,10 @@ This contains application service APIs which are used by the home server.
|
||||||
|
|
||||||
User Query ``[Draft]``
|
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.
|
This API is called by the HS to query the existence of a user on the Application Service's namespace.
|
||||||
|
|
||||||
Inputs:
|
Inputs:
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue