docs.ejabberd.im

API Versioning

Introduction

It is possible to support different versions of the ejabberd API (see the Global commands interface documentation for details on the ejabberd API). Only REST and command line frontends support versions, XML-RPC is not supported and can only use the latest API version. Versioning is used to ensure compatibility with third party backend using the API. When some commands are modified (either its declaration or its definition, breaking compatibility), those modifications can be done in a new version of the API, keeping the old commands still available in the previous API version.

An API version is an integer (sub-versions are not supported).

Command definition

If a command is modified, a new #ejabberd_commands record should be defined with a version attribute set to the API version (an integer) where this command version is available. There is no need to add a new #ejabberd_commands record for commands that are not modified in a given API version, immediate inferior version is used.

By default, all commands are in API version 0, and latest API is used if no version is specified when calling ejabberd_commands directly without specifying a version.

API usage

HTTP REST

To support a given HTTP REST API version, the ejabberd_http handler defined in the ejabberd.yml configuration file associated to mod_http_api must include a vN in its path, where N is an integer corresponding to the version.

Example:

    request_handlers:
      "/api/v1": mod_http_api  # API version 1 handler
      "/v2/api": mod_http_api  # API version 2 handler
  • If there is no vN in the handler path, the API version 0 is used.
  • In case there is several vN in the path the last one is used.

Command line

By default, when using ejabberdctl, the latest version a given command is used. To use a command in a specific API version, use the --version switch, followed by the version number, before the command name.

Example:

ejabberdctl --version 2 set_loglevel 4