Skip to content

Commit bbe0d3d

Browse files
badlopbadlop
committed
Improve some API Commands pages
1 parent 3f54b2e commit bbe0d3d

File tree

3 files changed

+129
-63
lines changed

3 files changed

+129
-63
lines changed

‎content/developer/ejabberd-api/api_versioning.md‎

Lines changed: 42 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,57 @@ By default, all commands are in API version 0, and latest API is used if no vers
3737
The command documentation indicates the api version as a tag: `v1`, `v2`...
3838
Commands not versioned do not have such a tag: they are version 0.
3939

40-
The [ejabberd Docs: API Tags](../ejabberd-api/admin-api.md) page lists the most recent API versions, and what commands are included.
40+
The [API Tags](../ejabberd-api/admin-api.md) page lists the most recent API versions, and what commands are included.
4141

4242
To know exactly what is the format expected for a command in a specific API version, use `ejabberdctl` specifying what API version you want to consult and the command name, for example:
4343

4444
``` sh
4545
ejabberdctl --version 0 help get_roster
4646
```
4747

48+
## `ejabberdctl`
49+
50+
[ejabberdctl](../../admin/guide/managing.md#ejabberdctl)
51+
uses by default the latest API version.
52+
53+
To execute a command from a specific API version, add the `--version` switch,
54+
followed by the version number, and then the command name.
55+
56+
Example:
57+
58+
``` sh
59+
ejabberdctl --version 2 set_loglevel 4
60+
```
61+
62+
Use the most recent API version:
63+
64+
``` sh
65+
$ ejabberdctl get_roster admin localhost
66+
jan@localhost jan none subscribe group1,group2
67+
tom@localhost tom none subscribe group3
68+
```
69+
70+
Use version 0:
71+
72+
``` sh
73+
$ ejabberdctl --version 0 get_roster admin localhost
74+
jan@localhost jan none subscribe group1;group2
75+
tom@localhost tom none subscribe group3
76+
```
77+
## `mod_adhoc_api`
78+
79+
[mod_adhoc_api](../../admin/configuration/modules.md#mod_adhoc_api)
80+
uses by default the latest API version.
81+
82+
If you want the module to use a specific API version,
83+
configure the module option `default_version`.
84+
4885
## `mod_http_api`
4986

50-
The server administrator can set the default version when configuring `request_handlers`, by including a `vN` in its path, where `N` is an integer corresponding to the version.
87+
[mod_http_api](../../admin/configuration/modules.md#mod_http_api)
88+
uses by default the latest API version.
89+
90+
You can set the default version when configuring `request_handlers`, by including a `vN` in its path, where `N` is an integer corresponding to the version.
5191

5292
In any case, the API client can specify a version when sending the request, by appending `vN` to the request path.
5393

@@ -97,30 +137,3 @@ $ curl -k -X POST -H "Content-type: application/json" \
97137
"info"
98138
```
99139

100-
## `ejabberdctl`
101-
102-
By default the latest version of a given command is used.
103-
To use a command in a specific API version, use the `--version` switch,
104-
followed by the version number, and then the command name.
105-
106-
Example:
107-
108-
``` sh
109-
ejabberdctl --version 2 set_loglevel 4
110-
```
111-
112-
Use the most recent API version:
113-
114-
``` sh
115-
$ ejabberdctl get_roster admin localhost
116-
jan@localhost jan none subscribe group1,group2
117-
tom@localhost tom none subscribe group3
118-
```
119-
120-
Use version 0:
121-
122-
``` sh
123-
$ ejabberdctl --version 0 get_roster admin localhost
124-
jan@localhost jan none subscribe group1;group2
125-
tom@localhost tom none subscribe group3
126-
```

‎content/developer/ejabberd-api/index.md‎

Lines changed: 82 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,88 @@
1-
# ejabberd Rest API
1+
# ejabberd ReST API
22

33
## Introduction
44

5-
ejabberd comes with a powerful API serving two goals:
6-
7-
1. Manage the XMPP service and integrate the platform with back-end platforms and script tools.
8-
2. Allow users to perform tasks via the client, allowing simple basic clients that do not need to use XMPP protocol.
9-
This can be handy, for example to send a message from your smartwatch, or show the number of offline messages.
10-
11-
The system is powerful and very versatile and you can configure it very finely, but it can be quite daunting to set up.
12-
13-
This section is written to demystify ejabberd API configuration and help you integrate ejabberd with your other back-ends or script through an HTTP / HTTPS ReST API.
14-
15-
## Understanding ejabberd "commands"
16-
17-
ejabberd operations are organised around the concept of commands. ejabberd standard modules already provide many commands, but the mechanism is generic and any module can provide its own set of commands. This exposition of commands for third-party modules make it very powerful.
18-
19-
All commands can be exposed through interfaces. Available interfaces are:
20-
21-
- [ejabberdctl](../../admin/guide/managing.md#ejabberdctl) command-line tool,
22-
- [mod_http_api](../../admin/configuration/modules.md#mod_http_api) for ReST calls using JSON data,
23-
- [ejabberd_xmlrpc](../../admin/configuration/listen.md#ejabberd_xmlrpc) for XML-RPC calls,
24-
- [WebAdmin](../../admin/guide/managing.md#web-admin) uses most commands to build the web pages,
25-
- [mod_configure](../../admin/configuration/modules.md#mod_configure) includes support for a few administrative tasks (using XMPP protocol itself through discovery and adhoc commands)
26-
27-
The [ejabberd-contrib Github repository](../../admin/guide/modules.md#ejabberd-contrib) provides other interfaces that can be installed to execute ejabberd commands in different ways: `mod_rest` (HTTP POST service), `mod_shcommands` (ejabberd WebAdmin page).
28-
29-
Any module in ejabberd can add its own command(s) through ejabberd Erlang/Elixir API, making the whole system totally extensible. A third-party module can expose its own command(s) and feel like a real part of the system. A module that exposes commands allows server admins to expose it the way they want.
30-
31-
ejabberd commands are universal, extensible and widely available through various configurable entrypoints.
32-
33-
_Note: The XML-RPC API still works but is deprecated in favor of the ReST API. You should migrate to ReST if you are using it._
34-
35-
<!-- TODO A diagram would be nice to have -->
5+
ejabberd comes with a extensive API that allows to perform administrative tasks from outside ejabberd:
6+
7+
1. Manage the XMPP server:
8+
restart the server, reload configuration, ...
9+
2. Integrate the XMPP server with your existing platforms:
10+
create a MUC room when a new party starts in your platform, ...
11+
3. Allow users to perform tasks using simple basic programs with no XMPP support:
12+
send a message from the smartwatch, show the number of offline messages...
13+
14+
The system is powerful, versatile, and you can configure access permissions very finely.
15+
In the next sections you will learn the basic concepts,
16+
how to start using ejabberd's API,
17+
how to adjust it to your needs,
18+
and integrate ejabberd with your existing systems.
19+
20+
## API Backends
21+
22+
ejabberd's API currently includes over 200 commands,
23+
see [API Reference](admin-api.md) for a detailed list of all the existing commands.
24+
Alternatively you can view the list of commands grouped by their [API Tags](admin-api.md).
25+
26+
Those commands are defined and implemented in Erlang or Elixir modules.
27+
Some modules included in ejabberd define their commands,
28+
while the majority of the existing commands are defined and implemented in:
29+
30+
- `ejabberd_admin`
31+
- [mod_admin_extra](../../admin/configuration/modules.md#mod_admin_extra)
32+
- [mod_muc_admin](../../admin/configuration/modules.md#mod_muc_admin)
33+
34+
When developing a module in Erlang or Elixir, it can define new commands,
35+
see [Commands](commands.md) page for details.
36+
37+
## API Frontends
38+
39+
The API commands are exposed through interfaces. Available interfaces are:
40+
41+
- [ejabberdctl](../../admin/guide/managing.md#ejabberdctl) command-line tool
42+
- [mod_http_api](../../admin/configuration/modules.md#mod_http_api) for HTTP ReST calls using JSON data
43+
- [mod_adhoc_api](../../admin/configuration/modules.md#mod_adhoc_api) for calls using a XMPP client
44+
- [WebAdmin](../../admin/guide/managing.md#web-admin) uses most commands to build the web pages
45+
- [ejabberd_xmlrpc](../../admin/configuration/listen.md#ejabberd_xmlrpc) for XML-RPC calls (deprecated in favor of mod_http_api)
46+
47+
There are other interfaces available in the [ejabberd-contrib](../../admin/guide/modules.md#ejabberd-contrib) Github repository:
48+
49+
- [mod_rest](https://github.com/processone/ejabberd-contrib/tree/master/mod_rest) for HTTP ReST calls using plaintext data
50+
- [mod_shcommands](https://github.com/processone/ejabberd-contrib/tree/master/mod_shcommands) for a WebAdmin page
51+
52+
## Process Flow
53+
54+
Let's review the process flow with one example:
55+
56+
1. API Client: Your web client (in this case Curl) sends an HTTP query
57+
1. API Frontend: [mod_http_api](../../admin/configuration/modules.md#mod_http_api)
58+
checks the client authentication,
59+
permissions to execute the command
60+
and processes command arguments, then calls
61+
1. API Backend: [mod_admin_extra](../../admin/configuration/modules.md#mod_admin_extra)
62+
actually executes the command.
63+
In this case, it will query to proper internal ejabberd code.
64+
65+
``` mermaid
66+
sequenceDiagram
67+
autonumber
68+
participant C as API Client<br/>curl
69+
box ejabberd
70+
participant F as API Frontend<br/>mod_http_api
71+
participant B as API Backend<br/>mod_admin_extra
72+
participant M as Module<br/>mod_last
73+
end
74+
Note right of C: HTTP Query
75+
C-->>F: POST /api/get_last<br/>{"user": "tom",<br/>"host": "localhost"}
76+
Note right of F: API Command Call
77+
F-->>B: get_last<br/>tom localhost
78+
Note right of B: Erlang Function Call
79+
B-->>M: mod_last:get_last_info<br/>(tom, localhost)
80+
activate M
81+
M-->>B: {ok,<br/>1743517196,<br/>"Disconnected"}
82+
deactivate M
83+
B-->>F: {"2025-04-01T14:19:56Z",<br/>"Disconnected"}
84+
F-->>C: 200 OK<br/>{"timestamp":<br/> "2025-04-01T14:19:56Z",<br/>"status":"Disconnected"}
85+
```
3686

3787
## The role of ejabberd API
3888

@@ -86,4 +136,3 @@ You can dig deeper into ejabberd ReST API configuration on the following pages:
86136

87137
- [API Permissions](permissions.md)
88138
- [OAuth Support](oauth.md)
89-
- [Administration API Commands](admin-api.md)

‎mkdocs.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,11 @@ markdown_extensions:
8383
pygments_lang_class: true
8484
- pymdownx.inlinehilite
8585
- pymdownx.snippets
86-
- pymdownx.superfences
86+
- pymdownx.superfences:
87+
custom_fences:
88+
- name: mermaid
89+
class: mermaid
90+
format: !!python/name:pymdownx.superfences.fence_code_format
8791
- pymdownx.tabbed:
8892
alternate_style: true
8993
- pymdownx.emoji:

0 commit comments

Comments
 (0)