First skeleton for REST backend

2017-09-17 01:06:43 +02:00
parent 23f717579e
commit 0cbf1a83a5
4 changed files with 392 additions and 0 deletions
--- a/docs/backends/rest.md
+++ b/docs/backends/rest.md
@@ -0,0 +1,145 @@
+# REST backend
+The REST backend allows you to query arbitrary REST JSON endpoints as backends for the following flows:
+- Identity lookup
+- Authentication
+
+## Configuration
+| Key                            | Default                               | Description                                          |
+---------------------------------|---------------------------------------|------------------------------------------------------|
+| rest.enabled                   | false                                 | Globally enable/disable the REST backend             |
+| rest.host                      | *empty*                               | Default base URL to use for the different endpoints. |
+| rest.endpoints.auth            | /_mxisd/identity/api/v1/auth          | Endpoint to validate credentials                     |
+| rest.endpoints.identity.single | /_mxisd/identity/api/v1/lookup/single | Endpoint to lookup a single 3PID                     |
+| rest.endpoints.identity.bulk   | /_mxisd/identity/api/v1/lookup/bulk   | Endpoint to lookup a list of 3PID                    |
+
+Endpoint values can handle two formats:
+- URL Path starting with `/` that gets happened to the `rest.host`
+- Full URL, if you want each endpoint to go to a specific server/protocol/port
+
+`rest.host` is only mandatory if at least one endpoint is not a full URL.
+
+## Endpoints
+### Authenticate
+Configured with `rest.endpoints.auth`
+
+HTTP method: `POST`  
+Encoding: JSON UTF-8
+  
+#### Request Body
+```
+{
+  "auth": {
+    "mxid": "@john.doe:example.org",
+    "localport": "john.doe",
+    "domain": "example.org",
+    "password": "passwordOfTheUser"
+  }
+}
+
+```
+
+#### Response Body
+If the authentication fails:
+```
+{
+  "auth": {
+    "success": false
+  }
+}
+```
+
+If the authentication succeed:  
+`auth.profile` and any sub-member are all optional
+```
+{
+  "auth": {
+    "success": true,
+    "mxid": "@john.doe:example.org",
+    "profile": {
+      "display_name": "John Doe",
+      "three_pids": [
+        {
+          "medium": "email",
+          "address": "john.doe@example.org"
+        },
+        {
+          "medium": "msisdn",
+          "address": "123456789"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Lookup
+#### Single
+Configured with `rest.endpoints.identity.single`
+
+HTTP method: `POST`  
+Encoding: JSON UTF-8  
+  
+#### Request Body
+```
+{
+  "lookup": {
+    "medium": "email",
+    "address": "john.doe@example.org"
+  }
+}
+```
+
+#### Response Body
+`lookup.uid` contains the Matrix ID localpart of the user
+
+```
+{
+  "lookup": {
+    "medium": "email",
+    "address": "john.doe@example.org",
+    "uid": "john"
+  }
+}
+
+```
+
+#### Bulk
+Configured with `rest.endpoints.identity.bulk`
+
+HTTP method: `POST`  
+Encoding: JSON UTF-8  
+  
+#### Request Body
+```
+{
+  "lookup": [
+    {
+      "medium": "email",
+      "address": "john.doe@example.org"
+    },
+    {
+      "medium": "msisdn",
+      "address: "123456789"
+    }
+  ]
+}
+```
+
+#### Response Body
+```
+{
+  "lookup": [
+    {
+      "medium": "email",
+      "address": "john.doe@example.org",
+      "uid": "john"
+    },
+    {
+      "medium": "msisdn",
+      "address: "123456789",
+      "uid": "jane"
+    }
+  ]
+}
+
+```