diff --git a/docs/backends/rest.md b/docs/backends/rest.md index 094e85a..b281d50 100644 --- 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": [] } -``` \ No newline at end of file +``` diff --git a/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java b/src/main/java/io/kamax/mxisd/config/rest/RestBackendConfig.java index d9a4295..005cfff 100644 --- 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 class RestBackendConfig { 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 class RestBackendConfig { 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 class RestBackendConfig { 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 index 708c83d..dbe31f7 100644 --- 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