Download API guide as PDFUsing the management API
This section describes how to use the Pexip Infinity management API.
It includes the following information:
Obtaining complete API information (schemas)
A summary of the schemas is available from within the Management Node via https://<manageraddress>/api/admin/schema/. If you require the schemas but do not have access to a Management Node running v11, please contact your authorized Pexip 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
All access to the management API is authenticated over HTTPS.
If you are not using an LDAP database for authentication, access is via the credentials for the web admin user. The default username for this account is admin.
If you are using an LDAP database, we recommend you create an account specifically for use by the API.
Examples used in the guide
This guide uses Python 2.7 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 will be admin.
Configuration replication delay
It may take some time between configuration being provided by the REST API and this configuration taking effect across the Conferencing Nodes. This delay is not usually more than approximately 60s, depending on load and network conditions.
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.
When configuration is modified, the modified configuration is replicated to the various Conferencing Nodes. This means that configuration changes will 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
Some guidelines for designing your application:
- Avoid duplication. Avoid designs which will perform large amounts of polling for information that is not needed or which will result in repeatedly writing the same configuration values.
- Consider application designs which 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.
- 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.
- 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.
Security
We recommend that you upload a HTTPS certificate to your Management Node and each Conferencing Node and that client applications verify those certificates, in order to undertake server validation.