Skip to content
Back to top
View this page

# Internal “API”

Slixmpp has a generic API registry that can be used by its plugins to allow access control, redefinition of behaviour, without having to inherit from the plugin or do more dark magic.

The idea is that each api call can be replaced, most of them use a form of in-memory storage that can be, for example, replaced with database or file-based storage.

Each plugin is assigned an API proxy bound to itself, but only a few make use of it.

See also Flexible internal API usage.

## Description of a generic API call

    def get_toto(jid, node, ifrom, args):
        return 'toto'

    self.xmpp.plugin['xep_XXXX'].api.register(handler, 'get_toto')

Each API call will receive 4 parameters (which can be `None` if data is not relevant to the operation), which are `jid` (`Optional[JID]`), `node` (`Optional[str]`), `ifrom` (`Optional[JID]`), and `args` (`Any`).

- `jid`, if relevant, represents the JID targeted by that operation

- `node`, if relevant is an arbitrary string, but was thought for, e.g., a pubsub or disco node.

- `ifrom`, if relevant, is the JID the event is coming from.

- `args` is the event-specific data passed on by the plugin, often a dict of arguments (can be None as well).

Note

Since 1.8.0, API calls can be coroutines.

## Handler hierarchy

The `self.api.register()` signature is as follows:

    def register(handler, op, jid=None, node=None, default=False):
        pass

As you can see, `register()` takes an additional ctype parameter, but the `APIWrapper` takes care of that for us (in most cases, it is the name of the XEP plugin, such as `'xep_0XXX'`).

When you register a handler, you register it for an `op`, for operation. For example, `get_vcard`.

`handler` and `op` are the only two required parameters (and in many cases, all you will ever need). You can, however, go further and register handlers for specific values of the `jid` and `node` parameters of the calls.

The priority of the execution of handlers is as follows:

- Check if a handler for both values of `node` and `jid` has been defined

- If not found, check if a handler for this value of `jid` has been defined

- If not found, check if a handler for this value of `node` has been defined

- If still not found, get the global handler (no parameter registered)

## Raw documentation

This documentation is provided for reference, but `register()` should be all you need.

class slixmpp.api.APIRegistry(xmpp)

  API Registry.

  This class is the global Slixmpp API registry, on which any handler will be registered.

  purge(ctype)

    Remove all information for a given API.

    Return type:

      `None`

  register(handler, ctype, op, jid=None, node=None, default=False)

    Register an API callback, with JID+node specificity.

    The API callback can later be executed based on the specificity of the provided JID+node combination.

    See `run()` for more details.

    Parameters:

      - ctype (`str`) – The name of the API to use.

      - op (`str`) – The API operation to perform.

      - jid (`JID` | `None`) – Optionally provide specific JID.

      - node (`str` | `None`) – Optionally provide specific node.

  register_default(handler, ctype, op)

    Register a default, global handler for an operation.

    Parameters:

      - handler – The default, global handler for the operation.

      - ctype (`str`) – The name of the API to modify.

      - op (`str`) – The API operation to use.

  restore_default(ctype, op, jid=None, node=None)

    Reset an API callback to use a default handler.

    Parameters:

      - ctype (`str`) – The name of the API to use.

      - op (`str`) – The API operation to perform.

      - jid (`JID` | `None`) – Optionally provide specific JID.

      - node (`str` | `None`) – Optionally provide specific node.

  run(ctype, op, jid=None, node=None, ifrom=None, args=None)

    Execute an API callback, based on specificity.

    The API callback that is executed is chosen based on the combination of the provided JID and node:

    JID | node | Handler
    --- | --- | ---
    Given | Given | Node + JID handler
    Given | None | JID handler
    None | Given | Node handler
    None | None | Global handler

    A node handler is responsible for servicing a single node at a single JID, while a JID handler may respond for any node at a given JID, and the global handler will answer to any JID+node combination.

    Handlers should check that the JID `ifrom` is authorized to perform the desired action.

    Changed in version 1.8.0: `run()` always returns a future, if the handler is a coroutine the future should be awaited on.

    Parameters:

      - ctype (`str`) – The name of the API to use.

      - op (`str`) – The API operation to perform.

      - jid (`JID` | `None`) – Optionally provide specific JID.

      - node (`str` | `None`) – Optionally provide specific node.

      - ifrom (`JID` | `None`) – Optionally provide the requesting JID.

      - args (`Any`) – Optional arguments to the handler.

    Return type:

      `Future`

  unregister(ctype, op, jid=None, node=None)

    Remove an API callback.

    The API callback chosen for removal is based on the specificity of the provided JID+node combination.

    See `run()` for more details.

    Parameters:

      - ctype (`str`) – The name of the API to use.

      - op (`str`) – The API operation to perform.

      - jid (`JID` | `None`) – Optionally provide specific JID.

      - node (`str` | `None`) – Optionally provide specific node.

  wrap(ctype)

    Return a wrapper object that targets a specific API.

    Return type:

      `APIWrapper`

class slixmpp.api.APIWrapper(api, name)

  Slixmpp API wrapper.

  This class provide a shortened binding to access `self.api` from plugins without having to specify the plugin name or the global `APIRegistry`.