Add docs for listener and schemas

doc/configuration/listen.md

@@ -492,6 +492,37 @@ Maximum allowed incoming stanza size.
 This subsection enables external component connections over WebSockets.
 See the [service](#xmpp-components-listenservice) listener section for details.
 
+### Handler types: GraphQL API - `mongoose_graphql_cowboy_handler`
+
+The recommended configuration is shown in [Example 2](#example-graphql-api) below.
+For more information about the API, see the [Admin interface](../graphql-api/Admin-GraphQL.md) and [User interface](../graphql-api/User-GraphQL.md) documentation.
+The following options are supported for this handler:
+
+#### `listen.http.handlers.mongoose_graphql_cowboy_handler.schema_endpoint`
+* **Syntax:** string, one of `"admin"`, `"domain_admin"`, `"user"`
+* **Default:** not set
+* **Example:** `schema_endpoint = "admin"`
+
+Specifies the schema:
+
+* `user` - user schema,
+* `domain_admin` - domain admin schema.
+* `admin` - admin schema.
+
+#### `listen.http.handlers.mongoose_graphql_cowboy_handler.username` - only for `admin`
+* **Syntax:** string
+* **Default:** not set
+* **Example:** `username = "admin"`
+
+When set, enables authentication for the admin API, otherwise it is disabled. Requires setting `password`.
+
+#### `listen.http.handlers.mongoose_graphql_cowboy_handler.password` - only for `admin`
+* **Syntax:** string
+* **Default:** not set
+* **Example:** `password = "secret"`
+
+Required to enable authentication for the admin API.
+
 ### Handler types: REST API - Admin - `mongoose_api_admin`
 
 The recommended configuration is shown in [Example 2](#example-2-admin-api) below.

doc/graphql-api/Admin-GraphQL.md

@@ -0,0 +1,52 @@
+# MongooseIM's GraphQL API for the administration
+
+The new GraphQL admin API contains all the commands available through the REST API, and the vast majority of the CTL commands. Only commands that wouldn't have worked well with GraphQL style have been omitted.
+
+We can distinguish two levels of the administration. A global admin (has access to all commands) and the admin per domain (has access only to the owned domain). Each of them is handled by a different endpoint. Please see the configuration [Listen](../../configuration/listen/#handler-types-graphql-api-mongoose_graphql_cowboy_handler) section for more details.
+
+There is only one schema for both admin types. Admin per domain simply has no permissions to execute global commands or to execute commands with not owned domain. The API documentation clearly says which commands are global.
+
+## Domain per admin configuration
+
+Out of the box, domains are created with disabled admin account. Admin per domain can be enabled only by the global admin with the command
+<a href="../admin-graphql-doc.html#definition-DomainAdminMutation" target="_blank" rel="noopener noreferrer">mutation.domains.setDomainPassword</a>. Afterwards the damain admin can change the password with the same command.
+
+The admin per domain can be disabled by the global admin with the command <a href="../admin-graphql-doc.html#definition-DomainAdminMutation" target="_blank" rel="noopener noreferrer">mutation.domains.removeDomainPassword</a>.
+
+## Authentication
+
+MongooseIM uses *Basic Authentication* as an authentication method for the GraphQL API.
+
+*Basic authentication* is a simple authentication scheme built into the HTTP protocol.
+Each HTTP request to the GraphQL API has to contain the Authorization header
+with the word `Basic` followed by a space and a base64-encoded string.
+
+### Global admin endpoint
+
+The authentication for global admin is optional because this endpoint shouldn't be exposed outside. The credentials can be set in the handler section in the config what enables the authentication.
+
+The base64-encoded string should have form
+`login:password`, where:
+
+- `login` is the login set in the config,
+- `password` is the password set in the config.
+
+Please see the [Authentication](#authentication) section for more details.
+
+### Domain admin endpoint
+
+For example, to authorize as `admin@localhost` with the password `secret`, the
+client would send a header:
+
+```
+Authorization: Basic YWxpY2VAbG9jYWxob3N0OnNlY3JldA==
+```
+
+## GraphiQL
+
+## API static documentation
+
+<a style="float: right; padding: 5px" href="../admin-graphql-doc.html" target="_blank" rel="noopener noreferrer">Open GraphQL documentation as a full page</a>
+
+<iframe src="../admin-graphql-doc.html"
+height="800" width="800" style="border: 1px solid black;"></iframe>

doc/graphql-api/User-GraphQL.md

@@ -0,0 +1,4 @@
+# MongooseIM's REST API for the user
+
+<iframe src="../user-graphql-doc.html"
+height="800" width="800" style="border: 1px solid black;"></iframe>

mkdocs.yml

@@ -144,6 +144,9 @@ nav:
       - 'Metrics backend': 'rest-api/Metrics-backend.md'
       - 'Administration backend': 'rest-api/Administration-backend.md'
       - 'Dynamic domains': 'rest-api/Dynamic-domains.md'
+  - 'GraphQL API':
+      - 'User': 'graphql-api/User-GraphQL.md'
+      - 'Admin': 'graphql-api/Admin-GraphQL.md'
   - 'Operation and Maintenance':
       - 'GDPR considerations': 'operation-and-maintenance/gdpr-considerations.md'
       - 'Cluster management considerations': 'operation-and-maintenance/Cluster-management-considerations.md'