Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Unified REST API docs #3780

Merged
merged 10 commits into from
Oct 3, 2022
Merged

Unified REST API docs #3780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
002f69b
Move Inbox REST API docs to Swagger
chrzaszcz Sep 28, 2022
637b606
Remove mod_*commands from the docs
chrzaszcz Sep 28, 2022
ff0401e
Move the swagger docs for the dynamic domains
chrzaszcz Sep 28, 2022
84baf70
Refer to the API docs for domain management
Sep 29, 2022
bc6a8e3
Update the API listener docs
Sep 29, 2022
4229ba6
Remove the deleted /commands endpoint from docs
Sep 29, 2022
e2230d8
Move metrics API docs to the Admin REST Swagger
Sep 29, 2022
22984b7
Return valid JSON value for Admin REST API errors
Sep 29, 2022
348b28c
Remove JSON error examples for domains
Sep 29, 2022
2d4ea88
Update migration guide with the REST API changes
Sep 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 0 additions & 13 deletions doc/configuration/Modules.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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