Using the management API

This section describes how to use the Pexip Infinity management API.

For more information and examples about how you can extract history data and view it in tools such as Excel and PowerBI, see Extracting and analyzing call data.

Obtaining complete API information (schemas)

A summary of the schemas is available from within the Management Node web interface via https://<manageraddress>/admin/platform/schema/. If you require the schemas but do not have access to a Management Node running v34, please contact your Pexip authorized support representative.

Full information for each configuration, command and resource is available from within the Management Node by downloading the resource's schema. The information in each schema includes, where applicable:

  • all the available fields
  • whether each field is optional or required
  • the type of data each field must contain
  • any restrictions on the minimum or maximum length of each field
  • help text with information on usage

See the Management command API, Management configuration API and Management status API sections for a list of all resources and how to access the schemas for each.

Authentication

There are three options for API authentication:

  • Using OAuth. This option allows the API to authenticate once to authorize access for a set amount of time, after which it must re-authenticate. This option is useful for environments where a large number of API requests are expected, because it reduces the number of requests sent to the LDAP server.
  • Using an LDAP database. In this case, each API request requires a preceding request to the LDAP server. If you are using an LDAP database, we recommend you create an account specifically for use by the API.
  • If you are not using OAuth or an LDAP database for authentication, access is via the credentials for the web admin user. The default username for this account is admin.

You can use OAuth on its own, LDAP on its own, or both together. Any access that is not via OAuth uses HTTP Basic Authentication over HTTPS.

Examples used in the guide

This guide uses Python 3 and the requests library (https://pypi.python.org/pypi/requests) for examples. However, many other modern programming languages and libraries exist which could be used equally successfully for driving the Pexip Infinity RESTful APIs.

The examples used are self-contained programs rather than pseudo code. These are given in an effort to help illustrate programming possibilities.

The following example data is used in the examples:

<manageraddress>: the IP address or FQDN of the Management Node.

<password1>: the admin web password for accessing the Management Node.

<user1>: the admin web username for accessing the Management Node. On a default installation this is admin.

Configuration replication delay

It may take some time for any configuration changes to take effect across the Conferencing Nodes. In typical deployments, configuration replication is performed approximately once per minute. However, in very large deployments (more than 60 Conferencing Nodes), configuration replication intervals are extended, and it may take longer for configuration changes to be applied to all Conferencing Nodes (the administrator log shows when each node has been updated).

API performance

Accessing the REST API on the Management Node requires that the Management Node lock access to its database to ensure that configuration remains consistent and coherent. This therefore limits the rate at which requests can be serviced (to 1,000 requests every 60 seconds).

When configuration is modified, the modified configuration is replicated to the various Conferencing Nodes. This means that configuration changes cause some CPU usage on both the Management Node and the Conferencing Nodes.

Heavy or frequent API usage will consume resources across the Pexip Infinity deployment.

API design guidelines and best practices

We recommend you follow these guidelines and best practices when designing your application, to minimize resource usage and network latency when using the API:

  • Use bulk requests, rather than individual requests. For example, the PATCH method can be used to create or update multiple objects at once. For more information, see Updating multiple resource objects; for an example of this in use, see Creating multiple Virtual Meeting Rooms.
  • Avoid duplication. Avoid designs that perform large amounts of polling for information that is not needed, or that result in repeatedly writing the same configuration values.
  • Consider application designs that avoid the need to make large numbers of requests concurrently. Although concurrent API requests will work they may not be processed in the order that they commence. Consider waiting for a request to complete before making another one.
  • In cases where multiple REST requests will be made sequentially in quick succession, consider using HTTP 1.1 connection keep alives and reusing your HTTPS connection in order to avoid the not insignificant handshake overhead of re-establishing separate HTTPS connections for every request.
  • Use a client with a TCP connection pool, to avoid repeatedly setting up TLS connections.
  • Be aware that other systems and applications in your deployment could also require access to the Management API, so consume the API as little as possible to ensure that they can also make use of it.
  • In situations where the Pexip Infinity is heavily loaded, API performance may be impaired. We therefore do not recommend using the API for real-time call admission control.
  • Very heavy usage of the API might cause the web-based Administrator interface performance to be impeded. Conversely, heavy Administrator interface usage might impair API performance.
  • If you are using the Management status API heavily, consider using Event sinks instead, to reduce the load on the Management Node.
  • All API URL paths must end with a / character. For example: https://<manageraddress>/api/admin/history/v1/participant/

    If the API URL path is appended with a query parameter, then the URL path does not require a / character at the end of the query parameter. For example: https://<manageraddress>/api/admin/configuration/v1/conference_alias/?offset=20

Security

We recommend that you upload a HTTPS certificate to your Management Node and each Conferencing Node, and that client applications verify those certificates when connecting to those servers. For more information, see Managing TLS and trusted CA certificates.