Prepare REST backend for directory flow

kamax-matrix · Oct 1, 2017 · 786e4a8 · 786e4a8
1 parent 8d0b0ed
commit 786e4a8
Show file tree

Hide file tree

Showing 3 changed files with 80 additions and 35 deletions.
diff --git a/docs/backends/rest.md b/docs/backends/rest.md
@@ -6,33 +6,33 @@ The REST backend allows you to query identity data in existing webapps, like:
 - self-hosted clouds (Nextcloud, ownCloud, ...)
 
 It supports the following mxisd flows:
-- Identity lookup
-- Authentication
+- [Authentication](#authentication)
+- [Directory](#directory)
+- [Identity](#identity)
 
 To integrate this backend with your webapp, you will need to implement three specific REST endpoints detailed below.
 
 
 ## 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 query a single 3PID                      |
-| rest.endpoints.identity.bulk   | /_mxisd/identity/api/v1/lookup/bulk   | Endpoint to query a list of 3PID                     |
+| 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/backend/api/v1/auth/login            | Validate credentials and get user profile            |
+| rest.endpoints.directory       | /_mxisd/backend/api/v1/directory/user/search | Search for users by arbitrary input                  |
+| rest.endpoints.identity.single | /_mxisd/backend/api/v1/identity/single       | Endpoint to query a single 3PID                      |
+| rest.endpoints.identity.bulk   | /_mxisd/backend/api/v1/identity/bulk         | Endpoint to query 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.
+`rest.host` is mandatory if at least one endpoint is not a full URL.
 
 ## Endpoints
-### Authenticate
-Configured with `rest.endpoints.auth`
-
+### Authentication
 HTTP method: `POST`  
-Encoding: JSON UTF-8
+Content-type: JSON UTF-8
 
 #### Request Body
 ```
@@ -84,12 +84,47 @@ If the authentication succeed:
 }
 ```
 
-### Lookup
-#### Single
-Configured with `rest.endpoints.identity.single`
+### Directory
+HTTP method: `POST`
+Content-type: JSON UTF-8
+
+#### Request Body
+```
+{
+  "search_term": "doe"
+}
+```
 
+#### Response Body:
+If users found:
+```
+{
+  "limited": false,
+  "results": [
+    {
+      "display_name": "John Doe",
+      "avatar_url": "http://domain.tld/path/to/avatar.png",
+      "user_id": "UserIdLocalpart"
+    },
+    {
+      ...
+    }
+  ]
+}
+```
+
+If no user found:
+```
+{
+  "limited": false,
+  "results": []
+}
+```
+
+### Identity
+#### Single 3PID lookup
 HTTP method: `POST`  
-Encoding: JSON UTF-8  
+Content-type: JSON UTF-8  
 
 #### Request Body
 ```
@@ -122,11 +157,9 @@ If no match was found:
 {}
 ```
 
-#### Bulk
-Configured with `rest.endpoints.identity.bulk`
-
+#### Bulk 3PID lookup
 HTTP method: `POST`  
-Encoding: JSON UTF-8  
+Content-type: JSON UTF-8  
 
 #### Request Body
 ```
@@ -175,4 +208,4 @@ If no match was found:
 {
   "lookup": []
 }
-```
+```
diff --git a/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java b/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java
@@ -60,16 +60,9 @@ public void setBulk(String bulk) {
 
     public static class Endpoints {
 
-        private IdentityEndpoints identity = new IdentityEndpoints();
         private String auth;
-
-        public IdentityEndpoints getIdentity() {
-            return identity;
-        }
-
-        public void setIdentity(IdentityEndpoints identity) {
-            this.identity = identity;
-        }
+        private String directory;
+        private IdentityEndpoints identity = new IdentityEndpoints();
 
         public String getAuth() {
             return auth;
@@ -79,6 +72,22 @@ public void setAuth(String auth) {
             this.auth = auth;
         }
 
+        public String getDirectory() {
+            return directory;
+        }
+
+        public void setDirectory(String directory) {
+            this.directory = directory;
+        }
+
+        public IdentityEndpoints getIdentity() {
+            return identity;
+        }
+
+        public void setIdentity(IdentityEndpoints identity) {
+            this.identity = identity;
+        }
+
     }
 
     private Logger log = LoggerFactory.getLogger(RestBackendConfig.class);
@@ -136,11 +145,13 @@ public void build() {
 
         if (isEnabled()) {
             endpoints.setAuth(buildEndpointUrl(endpoints.getAuth()));
+            endpoints.setDirectory(buildEndpointUrl(endpoints.getDirectory()));
             endpoints.identity.setSingle(buildEndpointUrl(endpoints.identity.getSingle()));
             endpoints.identity.setBulk(buildEndpointUrl(endpoints.identity.getBulk()));
 
             log.info("Host: {}", getHost());
             log.info("Auth endpoint: {}", endpoints.getAuth());
+            log.info("Directory endpoint: {}", endpoints.getDirectory());
             log.info("Identity Single endpoint: {}", endpoints.identity.getSingle());
             log.info("Identity Bulk endpoint: {}", endpoints.identity.getBulk());
         }

diff --git a/src/main/resources/application.yaml b/src/main/resources/application.yaml
@@ -37,10 +37,11 @@ lookup:
 
 rest:
   endpoints:
-    auth: "/_mxisd/identity/api/v1/auth"
+    auth: '/_mxisd/backend/api/v1/auth/login'
+    directory: '/_mxisd/backend/api/v1/directory/user/search'
     identity:
-      single: "/_mxisd/identity/api/v1/lookup/single"
-      bulk: "/_mxisd/identity/api/v1/lookup/bulk"
+      single: '/_mxisd/backend/api/v1/identity/lookup/single'
+      bulk: '/_mxisd/backend/api/v1/identity/lookup/bulk'
 
 ldap:
   enabled: false