Clarify README and REST backend doc

README.md

@@ -171,17 +171,26 @@ systemctl start mxisd
 After following the specific instructions to create a config file from the sample:
 1. Set the `matrix.domain` value to the domain value used in your Home Server configuration
 2. Set an absolute location for the signing keys using `key.path`
-3. Set a location for the default SQLite persistence using `storage.provider.sqlite.database`
+3. Configure the E-mail invite sender with items starting in `invite.sender.email`
-4. Configure the E-mail invite sender with items starting in `invite.sender.email`
 
 In case your IS public domain does not match your Matrix domain, see `server.name` and `server.publicUrl` 
 config items.
 
-If you want to use the LDAP backend:
+
+## Backends
+### LDAP (AD, Samba, LDAP)
+If you want to use LDAP backend as an Identity store:
 1. Enable it with `ldap.enabled`
 2. Configure connection options using items starting in `ldap.connection`
 3. You may want to valid default values for `ldap.attribute` items
 
+### SQL (SQLite, PostgreSQL)
+If you want to connect to use a synapse DB (SQLite or PostgreSQL) as Identity store, follow the example config for `sql` config items.
+
+### REST (Webapps/websites integration)
+If you want to use the REST backend as an Identity store:
+1. Enable it with `rest.enabled`
+2. Configure options starting with `rest` and see the dedicated documentation in `docs/backends/rest.md`
 
 # Network Discovery
 To allow other federated Identity Server to reach yours, the same algorithm used for Homeservers takes place:

docs/backends/rest.md

@@ -1,16 +1,25 @@
 # REST backend
-The REST backend allows you to query arbitrary REST JSON endpoints as backends for the following flows:
+The REST backend allows you to query identity data in existing webapps, like:
+- Forums (phpBB, Discourse, etc.)
+- Custom Identity stores (Keycloak, ...)
+- CRMs (Wordpress, ...)
+- self-hosted clouds (Nextcloud, ownCloud, ...)
+
+It supports the following mxisd flows:
 - Identity lookup
 - Authentication
 
+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 lookup a single 3PID                     |
+| 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 lookup a list of 3PID                    |
+| rest.endpoints.identity.bulk   | /_mxisd/identity/api/v1/lookup/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`