Skip to content

Commit

Permalink
Unified REST API docs (#3780)
Browse files Browse the repository at this point in the history 
* Move Inbox REST API docs to Swagger

* Remove mod_*commands from the docs

* Move the swagger docs for the dynamic domains

Merge the docs with the backend ones, just as the HTTP handlers are merged.

* Refer to the API docs for domain management

* Update the API listener docs

* Remove the deleted /commands endpoint from docs

* Move metrics API docs to the Admin REST Swagger

* Return valid JSON value for Admin REST API errors

Previously it was plain text, but the Content-Type was application/json
This caused issues with the interactive Swagger UI - it displayed "no
response from server". Now it displays the errors correctly.

Tests don't need changing, because they are decoding JSON
automatically, and the result is the same text as before.

* Remove JSON error examples for domains

They got outdated, and it is difficult to keep the up to date.
Moreover, for the remaining operations there are no error examples.

* Update migration guide with the REST API changes

Co-authored-by: Paweł Chrząszcz <[email protected]>
  • Loading branch information
@chrzaszcz
chrzaszcz and Paweł Chrząszcz committed Oct 3, 2022
1 parent 2c13138 commit b88ec04
Show file tree
Hide file tree
Showing 22 changed files with 397 additions and 889 deletions.
13 changes: 0 additions & 13 deletions doc/configuration/Modules.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,10 +70,6 @@ This module tightly cooperates with [mod_pubsub](../modules/mod_pubsub.md) in or
### [mod_carboncopy](../modules/mod_carboncopy.md)
Implements [XEP-0280: Message Carbons](http://xmpp.org/extensions/xep-0280.html) in order to keep all IM clients for a user engaged in a real-time conversation by carbon-copying all inbound and outbound messages to all interested resources (Full JIDs).

### [mod_commands](../modules/mod_commands.md)
A central gateway providing access to a subset of MongooseIM functions by channels other than XMPP.
Commands defined there are currently accessible via REST API.

### [mod_csi](../modules/mod_csi.md)
Enables the [XEP-0352: Client State Indication](http://xmpp.org/extensions/xep-0352.html) functionality.

Expand Down Expand Up @@ -106,9 +102,6 @@ Implements [XEP-0363: HTTP File Upload](https://xmpp.org/extensions/xep-0363.htm
### [mod_inbox](../modules/mod_inbox.md)
Implements custom inbox XEP

### [mod_inbox_commands](../modules/mod_inbox_commands.md)
Exposes administrative commands for the [inbox](../modules/mod_inbox.md)

### [mod_global_distrib](../modules/mod_global_distrib.md)
Enables sharing a single XMPP domain between distinct datacenters (**experimental**).

Expand All @@ -128,18 +121,12 @@ Implements [XEP-0313: Message Archive Management](http://xmpp.org/extensions/xep
Implements [XEP-0045: Multi-User Chat](http://xmpp.org/extensions/xep-0045.html), for a featureful multi-user text chat (group chat), whereby multiple XMPP users can exchange messages in the context of a chat room.
It is tightly coupled with user presence in chat rooms.

### [mod_muc_commands](../modules/mod_muc_commands.md)
Provides `mod_muc` related `mongoose_commands`, accessible via the client REST API.

### [mod_muc_log](../modules/mod_muc_log.md)
Implements a logging subsystem for [mod_muc](../modules/mod_muc.md).

### [mod_muc_light](../modules/mod_muc_light.md)
Implements [XEP Multi-User Chat Light](https://xmpp.org/extensions/inbox/muc-light.html).

### [mod_muc_light_commands](../modules/mod_muc_light_commands.md)
Provides `mod_muc_light` related `mongoose_commands`, accessible via client REST API.

### [mod_offline](../modules/mod_offline.md)
Provides an offline messages storage that is compliant with [XEP-0160: Best Practices for Handling Offline Messages](http://xmpp.org/extensions/xep-0160.html).

Expand Down
3 changes: 1 addition & 2 deletions doc/configuration/general.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,7 @@ In order to configure these hosts independently, use the [`host_config` section]

This is the list of names for the types of hosts that will serve dynamic XMPP domains.
Each host type can be seen as a label for a group of independent domains that use the same server configuration.
In order to configure these host types independently, use the [`host_config` section](./host_config.md).
The domains can be added or removed dynamically via the [dynamic domains REST API](../rest-api/Dynamic-domains.md).
In order to configure these host types independently, use the [`host_config` section](./host_config.md). The domains can be added or removed dynamically with the [command line interface](../../developers-guide/domain_management#command-line-interface) or using the [API](../../developers-guide/domain_management#api).

If you use the host type mechanism, make sure you only configure modules which support dynamic domains in the [`modules`](./Modules.md) or [`host_config.modules`](./host_config.md#host_configmodules) sections.
MongooseIM will **not** start otherwise.
Expand Down
152 changes: 56 additions & 96 deletions doc/configuration/listen.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -399,7 +399,7 @@ The shaper named `fast` needs to be defined in the `shaper` section.

## HTTP-based services: `[[listen.http]]`

Manages all HTTP-based services, such as BOSH (HTTP long-polling), WebSocket and REST.
Manages all HTTP-based services, such as BOSH (HTTP long-polling), WebSocket, GraphQL and REST.
It uses the [Cowboy](https://ninenines.eu/docs/en/cowboy/2.6/manual) web server.
Recommended port number: 5280 for BOSH/WS.

Expand All @@ -411,7 +411,7 @@ There are the following options for each of the HTTP listeners:
* `mod_bosh` - for [BOSH](https://xmpp.org/extensions/xep-0124.html) connections,
* `mod_websockets` - for [WebSocket](https://tools.ietf.org/html/rfc6455) connections,
* `mongoose_graphql_cowboy_handler` - for GraphQL API,
* `mongoose_api_admin`, `mongoose_api_client`(obsolete), `mongoose_client_api`, `mongoose_domain_handler`, `mongoose_api` - for REST API.
* `mongoose_admin_api`, `mongoose_client_api` - for REST API.

These types are described below in more detail.
The double-bracket syntax is used because there can be multiple handlers of a given type, so for each type there is a TOML array of one or more tables (subsections).
Expand Down Expand Up @@ -505,9 +505,9 @@ The following options are supported for this handler:

Specifies the schema endpoint:

* `admin` - Endpoint with the admin commands. A global admin has permission to execute all commands. See the recommended configuration - [Example 5](#example-5-admin-graphql-api).
* `domain_admin` - Endpoint with the admin commands. A domain admin has permission to execute only commands with the owned domain. See the recommended configuration - [Example 6](#example-6-domain-admin-graphql-api).
* `user` - Endpoint with the user commands. Used to manage the authorized user. See the recommended configuration - [Example 7](#example-7-user-graphql-api).
* `admin` - Endpoint with the admin commands. A global admin has permission to execute all commands. See the recommended configuration - [Example 2](#example-2-admin-graphql-api).
* `domain_admin` - Endpoint with the admin commands. A domain admin has permission to execute only commands with the owned domain. See the recommended configuration - [Example 3](#example-3-domain-admin-graphql-api).
* `user` - Endpoint with the user commands. Used to manage the authorized user. See the recommended configuration - [Example 4](#example-4-user-graphql-api).

#### `listen.http.handlers.mongoose_graphql_cowboy_handler.username` - only for `admin`
* **Syntax:** string
Expand All @@ -523,40 +523,47 @@ When set, enables authentication for the admin API, otherwise it is disabled. Re

Required to enable authentication for the admin API.

### Handler types: REST API - Admin - `mongoose_api_admin`
### Handler types: REST API - Admin - `mongoose_admin_api`

The recommended configuration is shown in [Example 2](#example-2-admin-api) below.
The recommended configuration is shown in [Example 5](#example-5-admin-rest-api) below.
For more information about the API, see the [REST interface](../rest-api/Administration-backend.md) documentation.
The following options are supported for this handler:

#### `listen.http.handlers.mongoose_api_admin.username`
#### `listen.http.handlers.mongoose_admin_api.username`
* **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_api_admin.password`
#### `listen.http.handlers.mongoose_admin_api.password`
* **Syntax:** string
* **Default:** not set
* **Example:** `password = "secret"`

Required to enable authentication for the admin API.

#### `listen.http.handlers.mongoose_admin_api.handlers`
* **Syntax:** array of strings. Allowed values: `"contacts"`, `"users"`, `"sessions"`, `"messages"`, `"stanzas"`, `"muc_light"`, `"muc"`, `"inbox"`, `"domain"`, `"metrics"`.
* **Default:** all API handler modules enabled
* **Example:** `handlers = ["domain"]`

The admin API consists of several handler modules, each of them implementing a subset of the functionality.
By default all modules are enabled, so you don't need to change this option.

### Handler types: REST API - Client - `mongoose_client_api`

The recommended configuration is shown in [Example 3](#example-3-client-api) below.
The recommended configuration is shown in [Example 6](#example-6-client-rest-api) below.
Please refer to [REST interface](../rest-api/Client-frontend.md) documentation for more information.
The following options are supported for this handler:

#### `listen.http.handlers.mongoose_client_api.handlers`
* **Syntax:** array of strings - Erlang modules
* **Syntax:** array of strings. Allowed values: `"sse"`, `"messages"`, `"contacts"`, `"rooms"`, `"rooms_config"`, `"rooms_users"`, `"rooms_messages"`.
* **Default:** all API handler modules enabled
* **Example:** `handlers = ["mongoose_client_api_messages", "mongoose_client_api_sse"]`
* **Example:** `handlers = ["messages", "sse"]`

The client API consists of several modules, each of them implementing a subset of the functionality.
The client API consists of several handler modules, each of them implementing a subset of the functionality.
By default all modules are enabled, so you don't need to change this option.
For a list of allowed modules, you need to consult the [source code](https://github.com/esl/MongooseIM/blob/master/src/mongoose_client_api/mongoose_client_api.erl).

#### `listen.http.handlers.mongoose_client_api.docs`
* **Syntax:** boolean
Expand All @@ -566,38 +573,6 @@ For a list of allowed modules, you need to consult the [source code](https://git
The Swagger documentation of the client API is hosted at the `/api-docs` path.
You can disable the hosted documentation by setting this option to `false`.

### Handler types: REST API - Domain management - `mongoose_domain_handler`

The recommended configuration is shown in [Example 4](#example-4-domain-api) below.
This handler enables dynamic domain management for different host types.
For more information about the API, see the [REST interface](../rest-api/Dynamic-domains.md) documentation.
The following options are supported for this handler:

#### `listen.http.handlers.mongoose_domain_handler.username`
* **Syntax:** string
* **Default:** not set
* **Example:** `username = "admin"`

When set, enables authentication to access this endpoint. Requires setting password.

#### `listen.http.handlers.mongoose_domain_handler.password`
* **Syntax:** string
* **Default:** not set
* **Example:** `password = "secret"`

Required to enable authentication for this endpoint.

### Handler types: Metrics API (obsolete) - `mongoose_api`

REST API for accessing the internal MongooseIM metrics.
Please refer to the [REST interface to metrics](../rest-api/Metrics-backend.md) page for more information.
The following option is required:

#### `listen.http.handlers.mongoose_api.handlers`
* **Syntax:** array of strings - Erlang modules
* **Default:** all API handler modules enabled
* **Example:** `handlers = ["mongoose_api_metrics"]`

### Transport options

The options listed below are used to modify the HTTP transport settings.
Expand Down Expand Up @@ -661,10 +636,9 @@ The following listener accepts BOSH and WebSocket connections and has TLS config
path = "/ws-xmpp"
```

#### Example 2. Admin API
#### Example 2. Admin GraphQL API

REST API for administration, the listener is bound to `127.0.0.1` for increased security.
The number of acceptors and connections is specified (reduced).
GraphQL API for administration, the listener is bound to 127.0.0.1 for increased security. The number of acceptors and connections is specified (reduced).

```toml
[[listen.http]]
Expand All @@ -673,47 +647,53 @@ The number of acceptors and connections is specified (reduced).
transport.num_acceptors = 5
transport.max_connections = 10

[[listen.http.handlers.mongoose_api_admin]]
[[listen.http.handlers.mongoose_graphql_cowboy_handler]]
host = "localhost"
path = "/api"
path = "/api/graphql"
schema_endpoint = "admin"
username = "admin"
password = "secret"
```

#### Example 3. Client API
#### Example 3. Domain Admin GraphQL API

REST API for clients.
GraphQL API for the domain admin.

```toml
[[listen.http]]
port = 8089
ip_address = "0.0.0.0"
port = 5041
transport.num_acceptors = 10
transport.max_connections = 1024
protocol.compress = true

[[listen.http.handlers.mongoose_client_api]]
[[listen.http.handlers.mongoose_graphql_cowboy_handler]]
host = "_"
path = "/api"
path = "/api/graphql"
schema_endpoint = "domain_admin"
```

#### Example 4. Domain API
#### Example 4. User GraphQL API

REST API for domain management.
GraphQL API for the user.

```toml
[[listen.http]]
ip_address = "127.0.0.1"
port = 8088
ip_address = "0.0.0.0"
port = 5061
transport.num_acceptors = 10
transport.max_connections = 1024

[[listen.http.handlers.mongoose_domain_handler]]
host = "localhost"
path = "/api"
username = "admin"
password = "secret"
[[listen.http.handlers.mongoose_graphql_cowboy_handler]]
host = "_"
path = "/api/graphql"
schema_endpoint = "user"
```

#### Example 5. Admin GraphQL API
#### Example 5. Admin REST API

GraphQL API for administration, the listener is bound to 127.0.0.1 for increased security. The number of acceptors and connections is specified (reduced).
REST API for administration, the listener is bound to `127.0.0.1` for increased security.
The number of acceptors and connections is specified (reduced).
Basic HTTP authentication is used as well.

```toml
[[listen.http]]
Expand All @@ -722,44 +702,24 @@ GraphQL API for administration, the listener is bound to 127.0.0.1 for increased
transport.num_acceptors = 5
transport.max_connections = 10

[[listen.http.handlers.mongoose_graphql_cowboy_handler]]
[[listen.http.handlers.mongoose_admin_api]]
host = "localhost"
path = "/api/graphql"
schema_endpoint = "admin"
path = "/api"
username = "admin"
password = "secret"
```

#### Example 6. Domain Admin GraphQL API
#### Example 6. Client REST API

GraphQL API for the domain admin.

```toml
[[listen.http]]
ip_address = "0.0.0.0"
port = 5041
transport.num_acceptors = 10
transport.max_connections = 1024

[[listen.http.handlers.mongoose_graphql_cowboy_handler]]
host = "_"
path = "/api/graphql"
schema_endpoint = "domain_admin"
```

#### Example 7. User GraphQL API

GraphQL API for the user.
REST API for clients.

```toml
[[listen.http]]
ip_address = "0.0.0.0"
port = 5061
transport.num_acceptors = 10
port = 8089
transport.max_connections = 1024
protocol.compress = true

[[listen.http.handlers.mongoose_graphql_cowboy_handler]]
[[listen.http.handlers.mongoose_client_api]]
host = "_"
path = "/api/graphql"
schema_endpoint = "user"
path = "/api"
```
Loading

0 comments on commit b88ec04

Please sign in to comment.