Management configuration API
Configuration of the Pexip Infinity platform and services can be performed through the REST API, allowing you to create, view, edit and delete items.
Configuration resources
The following configuration resources are available via the REST API:
Component | Path |
---|---|
System configuration | |
DNS server | /api/admin/configuration/v1/dns_server/ |
NTP server | /api/admin/configuration/v1/ntp_server/ |
Syslog server | /api/admin/configuration/v1/syslog_server/ |
SNMP NMS | /api/admin/configuration/v1/snmp_network_management_system |
VM manager | /api/admin/configuration/v1/host_system/ |
Static route | /api/admin/configuration/v1/static_route/ |
Platform configuration | |
System location | /api/admin/configuration/v1/system_location/ |
Management Node | /api/admin/configuration/v1/management_vm/ |
Conferencing Node | /api/admin/configuration/v1/worker_vm/ |
Licensing | /api/admin/configuration/v1/licence/ |
License request | /api/admin/configuration/v1/licence_request/ |
CA certificate | /api/admin/configuration/v1/ca_certificate/ |
Global settings | /api/admin/configuration/v1/global/ |
Call control | |
H.323 Gatekeeper | /api/admin/configuration/v1/h323_gatekeeper/ |
SIP credentials | /api/admin/configuration/v1/sip_credential/ |
SIP proxy | /api/admin/configuration/v1/sip_proxy/ |
Microsoft SIP proxy | /api/admin/configuration/v1/mssip_proxy/ |
TURN server | /api/admin/configuration/v1/turn_server/ |
STUN server | /api/admin/configuration/v1/stun_server/ |
Policy server | /api/admin/configuration/v1/policy_server/ |
Service configuration | |
Virtual Meeting Room, Virtual Auditorium or Virtual Reception | /api/admin/configuration/v1/conference/ |
Alias for a Virtual Meeting Room, Virtual Auditorium or Virtual Reception | /api/admin/configuration/v1/conference_alias/ |
Automatically Dialed Participant | /api/admin/configuration/v1/automatic_participant/ |
IVR theme | /api/admin/configuration/v1/ivr_theme/ |
Gateway routing rule | /api/admin/configuration/v1/gateway_routing_rule/ |
Registration settings | /api/admin/configuration/v1/registration/ |
Device | /api/admin/configuration/v1/device/ |
Conference sync template | /api/admin/configuration/v1/conference_sync_template/ |
Conference LDAP sync source | /api/admin/configuration/v1/ldap_sync_source/ |
Conference LDAP sync field * | /api/admin/configuration/v1/ldap_sync_field/ |
Users | |
Authentication | /api/admin/configuration/v1/authentication/ |
Account role | /api/admin/configuration/v1/role/ |
LDAP role | /api/admin/configuration/v1/ldap_role/ |
Permission | /api/admin/configuration/v1/permission/ |
Utilities | |
Upgrade | /api/admin/configuration/v1/upgrade/ |
System backup | /api/admin/configuration/v1/system_backup/ |
* This resource is new in Pexip Infinity v11. |
Resource details
More information can be obtained for each resource by downloading the resource schema in a browser.
You may wish to install a JSON viewer extension to your browser in order to view the JSON strings in a readable format.
For example, to view the schema for aliases the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/schema/?format=json
Each schema contains information on the available fields including:
- whether the field is optional (
nullable: true
) or required (nullable: false
) - the type of data the field must contain
- help text with additional information on usage
- which criteria can be used for filtering searches.
Resource methods
Each configuration resource supports the following HTTP methods:
Method | Action |
---|---|
GET | Retrieves the current configuration for a resource |
POST | Creates a new object for the resource |
PATCH | Updates an existing resource object, or creates the object if it does not already exist |
DELETE | Deletes an existing resource object |
Getting a single resource object
By concatenating an object ID with the resource URI, details can be obtained for a single resource object.
For example, to GET the alias with ID 1 the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/1/
The response to a GET for a single resource will be a JSON object with attributes for each field of the resource.
Getting multiple resource objects
If a GET operation is invoked on the root resource URI then details about multiple objects will be returned. The response to a GET for multiple resources will be a JSON object with two attributes:
Attribute | Value |
---|---|
meta | This will be an object giving meta information about the response. |
objects | This will be a list of resource objects. |
Pagination
By default, the response will be paginated and the response will contain the first page of 20 results. To retrieve subsequent pages of results the offset
parameter must be specified in the URI.
To carry on from our previous example, to retrieve the second page of results the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?offset=20
The limit
parameter can be used to change the number of results in the response.
For example, to return the first 100 objects the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?limit=100
Note that if there are a large number of aliases configured this may put a significant load on both the Management Node and the client making the request.
Filtering
A request for multiple objects can be filtered so that only those objects that match specific criteria are returned.
The following match specifiers are available:
Specifier | Description |
---|---|
exact | Matches objects whose field exactly matches the value. |
iexact | Case-insensitive version of the exact match. |
contains | Matches objects whose field contains the value. |
icontains | Case-insensitive version of the contains match. |
startswith | Matches objects whose field starts with the value. |
istartswith | Case-insensitive version of the startswith match. |
endswith | Matches objects whose field ends with the value. |
iendswith | Case-insensitive version of the endswith match. |
regex | Matches objects whose field matches the regular expression value. |
iregex | Case-insensitive version of the regex match. |
lt | Matches objects whose field is less than the value. |
lte | Matches objects whose field is less than or equal to the value. |
gt | Matches objects whose field is greater than the value. |
gte | Matches objects whose field is greater than or equal to the value. |
The criteria that can be used for filtering are included at the end of the schema for each resource. If no filtering
section is present, then filtering is not available.
For example, to see which criteria you can use to filter a search for Virtual Meeting Room, look at the associated schema:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/schema/?format=json
You will see at the end:
filtering: { alias: 1, conference: 2, description: 1 }
This indicates that you can filter by any of the criteria listed above. The 1
and 2
following each criteria indicate that all of the match specifiers listed in the table above are valid when filtering using that criteria. Alternatively, if not all specifiers are valid, those that are will be listed instead.
For example, to search for information about the alias meet.alice the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?alias=meet.alice
For example, to search for all aliases that start with meet. the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/?alias__startswith=meet.
Ordering
A request for multiple objects can be ordered by field values.
For example, to get the conference history ordered by start time the URI would be:
https://<manageraddress>/api/admin/history/v1/conference/?order_by=start_time
The order can be reversed by adding a hyphen character (-
)before the field name.
For example, to order by descending start time so that the most recent conferences are listed first the URI would be:
https://<manageraddress>/api/admin/history/v1/conference/?order_by=-start_time
The fields that can be used for ordering are included at the end of the schema for each resource. If no ordering section is present, then ordering is not available.
Creating a single resource object
To create a new object resource, a POST request is submitted to the root URI for the resource. The data should be a JSON object whose attributes match the field values for the resource.
Fields with default values may be omitted from the data.
The response to the POST method will contain a Location header which contains the REST URI of the newly created resource.
Updating a single resource object
To update a single resource object, a PATCH request is submitted to the URI created by concatenating the object ID with the root URI of the resource.
For example, to make changes to the alias with ID 1 the URI would be:
https://<manageraddress>/api/admin/configuration/v1/conference_alias/1/
Updating multiple resource objects
The PATCH method can be used to create or update multiple objects at once. To update multiple objects a PATCH request is submitted to the root URI for the resource. The data must be formatted as a JSON object with a single attribute objects
whose value is a list of the new objects.
Note: for any objects in the list that already exist, the resource_uri
field must be included in the request. For any objects that are to be created by the PATCH request, the resource_uri
field should be omitted.
Deleting all resource objects
If a DELETE operation is invoked on the root resource URI, then all the resource objects will be deleted. You should therefore use this operation with caution, and ensure you include the resource ID in the URI unless your intention actually is to delete all objects.
For example, to delete ALL Virtual Meeting Rooms, the URI is:
"https://<manageraddress>/api/admin/configuration/v1/conference/"
whereas to delete the Virtual Meeting Room with ID 1 only, the URI is:
"https://<manageraddress>/api/admin/configuration/v1/conference/1/"
Examples
Here are some configuration API examples:
- Creating a Virtual Meeting Room, Virtual Auditorium or Virtual Reception
- Getting a Virtual Meeting Room's configuration
- Changing an existing Virtual Meeting Room
- Deleting a Virtual Meeting Room
- Creating a Virtual Meeting Room with aliases
- Getting all Virtual Meeting Rooms, Virtual Auditoriums and Virtual Receptions
- Getting all Virtual Meeting Rooms only
- Creating multiple Virtual Meeting Rooms
- Creating a Virtual Auditorium
- Creating a Virtual Reception
- Creating Automatically Dialed Participants
- Modifying an Automatically Dialed Participant
- Removing an Automatically Dialed Participant from a Virtual Meeting Room
- Deleting an Automatically Dialed Participant
- Creating Gateway Routing Rules
- Deleting a Gateway Routing Rule
- Deploying a new Conferencing Node
- Downloading a Conferencing Node for manual deployment
- Deploying a Conferencing Node using a VM template and configuration file
- Uploading a service theme
Creating a Virtual Meeting Room, Virtual Auditorium or Virtual Reception
To create a new Virtual Meeting Room, Virtual Auditorium or Virtual Reception, you must submit a POST to the URI for this resource. You must specify the service_type
as follows:
conference
for a Virtual Meeting Roomlecture
for a Virtual Auditoriumtwo_stage_dialing
for a Virtual Reception
If you do not specify a service_type
, the service will by default be created as a Virtual Meeting Room.
The following example creates a new Virtual Meeting Room with the name VMR_1. It has no aliases.
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/conference/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({'name': 'VMR_1', 'service_type': 'conference'}) ) print "Created new Virtual Meeting Room:", response.headers['location']
Getting a Virtual Meeting Room's configuration
By submitting a GET to the resource URI of the new Virtual Meeting Room, you can get the Virtual Meeting Room configuration:
import json import requests response = requests.get( "https://<manageraddress>/api/admin/configuration/v1/conference/1/", auth=('<user1>', '<password1>'), verify=False ) print "Virtual Meeting Room:", json.loads(response.text)
Example output
Virtual Meeting Room: { 'aliases': [ { 'conference': '/api/admin/configuration/v1/conference/1/', 'alias': 'meet@example.com', 'description': '', 'id': 1 } ] 'allow_guests': False, 'automatic_participants': [], 'description': '', 'force_presenter_into_main': False, 'guest_pin': '', 'guest_view': None, 'host_view': 'one_main_seven_pips', 'id': 1, 'ivr_theme': None, 'max_callrate_in': None, 'max_callrate_out': None, 'name': 'VMR_1', 'participant_limit': None, 'pin': '', 'resource_uri': '/api/admin/configuration/v1/conference/1/', 'service_type': 'conference', 'sync_tag': '', 'tag': '' }
Changing an existing Virtual Meeting Room
Submitting a PATCH to an existing Virtual Meeting Room URI allows the data for that Virtual Meeting Room to be modified.
The following example updates the Virtual Meeting Room PIN to 1234:
import json import requests response = requests.patch( "https://<manageraddress>/api/admin/configuration/v1/conference/1/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({'pin': '1234'}) )
Adding a Virtual Meeting Room alias
A Virtual Meeting Room must already exist before you can add an alias to it. To do this you submit a POST to the resource URI for Virtual Meeting Room aliases and add the partial URI of the Virtual Meeting Room to the data POSTed.
The following example creates a new alias meet@example.com for the Virtual Meeting Room with ID 1.
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/conference_alias/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'alias': 'meet@example.com', 'conference': '/api/admin/configuration/v1/conference/1/', }) ) print "Created new alias:", response.headers['location']
Deleting a Virtual Meeting Room
Deleting a Virtual Meeting Room is achieved by submitting a DELETE request to an existing Virtual Meeting Room URI.
The following example deletes the Virtual Meeting Room with ID 1:
import requests response = requests.delete( "https://<manageraddress>/api/admin/configuration/v1/conference/1/", auth=('<user1>', '<password1>'), verify=False )
Deleting a Virtual Meeting Room will also delete all aliases associated with it.
Creating a Virtual Meeting Room with aliases
To simplify the creation of a Virtual Meeting Room and the aliases that belong to it, it is possible to submit a single POST with all the information.
The following example creates a new Virtual Meeting Room with the name VMR_1 and two aliases: meet and meet@example.com:
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/conference/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'name': 'VMR_1', 'service_type': 'conference', 'aliases': [{'alias' : 'meet'}, {'alias' : 'meet@example.com'}] }) ) print "Created new Virtual Meeting Room:", response.headers['location']
Getting all Virtual Meeting Rooms, Virtual Auditoriums and Virtual Receptions
Retrieving all the configured Virtual Meeting Rooms, Virtual Auditoriums and Virtual Receptions is achieved by submitting a GET request to the resource URI they all share:
import json import requests response = requests.get( "https://<manageraddress>/api/admin/configuration/v1/conference/", auth=('<user1>', '<password1>'), verify=False ) print "Virtual Meeting Rooms:", json.loads(response.text)['objects']
Getting all Virtual Meeting Rooms only
To retrieve all the configured Virtual Meeting Rooms but not Virtual Auditoriums or Virtual Receptions, you submit a GET request to the resource URI as above but filter it by service_type
:
import json import requests response = requests.get( "https://<manageraddress>/api/admin/configuration/v1/conference/?service_type=conference", auth=('<user1>', '<password1>'), verify=False ) print "Virtual Meeting Rooms:", json.loads(response.text)['objects']
Creating multiple Virtual Meeting Rooms
Multiple Virtual Meeting Rooms can be created using a PATCH request.
The following example creates two Virtual Meeting Rooms; the first with the name VMR_1 and an alias meet1@example.com, and the second with the name VMR_2 and an alias meet2@example.com:
import json import requests data = { 'objects' : [ {'name' : 'VMR_1', 'service_type': 'conference', 'aliases' : [{'alias' : 'meet1@example.com'}]}, {'name' : 'VMR_2', 'service_type': 'conference', 'aliases' : [{'alias' : 'meet2@example.com'}]}, ]} response = requests.patch( "https://<manageraddress>/api/admin/configuration/v1/conference/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps(data) )
Creating a Virtual Auditorium
The following example creates a new Virtual Auditorium with the name Lecture and a single alias lecture@example.com:
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/conference/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'name': 'Lecture', 'service_type': 'lecture', 'aliases': [{'alias' : 'lecture@example.com'}] }) ) print "Created new Virtual Auditorium:", response.headers['location']
Creating a Virtual Reception
The following example creates a new Virtual Reception with the name Reception and a single alias reception@example.com:
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/conference/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'name': 'Reception', 'service_type': 'two_stage_dialing', 'aliases': [{'alias' : 'reception@example.com'}] }) ) print "Created new Virtual Reception:", response.headers['location']
Creating Automatically Dialed Participants
You can create a new Automatically Dialed Participant by submitting a POST request to the resource URI for Automatically Dialed Participants. Automatically dialed participants are a little different from other resources as they may be associated with many different Virtual Meeting Rooms and Virtual Auditoriums.
The following example creates an Automatically Dialed Participant and associates them with an already created Virtual Meeting Room with ID 1:
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/automatic_participant/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'alias' : 'myendpoint@mydomain.com', 'description' : "Dial myendpoint@mydomain.com whenever a related conference starts", 'protocol' : 'sip', 'role' : 'guest', 'conference' : ['/api/admin/configuration/v1/conference/1/'] }) ) print "Created new automatically dialed participant:", response.headers['location']
Modifying an Automatically Dialed Participant
The following examples use PATCH to modify an existing Automatically Dialed Participant.
The example below associates the Automatically Dialed Participant (created above) with two (already created) Virtual Meeting Rooms — one with ID 1, one with ID 2:
import json import requests response = requests.patch( "https://<manageraddress>/api/admin/configuration/v1/automatic_participant/1/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'conference' : ['/api/admin/configuration/v1/conference/1/', '/api/admin/configuration/v1/conference/2/'] }) ) print "added existing automatic participant to an additional meeting room:", response
Removing an Automatically Dialed Participant from a Virtual Meeting Room
The example below removes the association between the Automatically Dialed Participant and the Virtual Meeting Rooms:
import json import requests response = requests.patch( "https://<manageraddress>/api/admin/configuration/v1/automatic_participant/1/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'conference' : [] }) ) print "Removed automatic participant from all meeting rooms:", response
Deleting an Automatically Dialed Participant
The following example deletes the Automatically Dialed Participant with ID 1:
import requests response = requests.delete( "https://<manageraddress>/api/admin/configuration/v1/automatic_participant/1/", auth=('<user1>', '<password1>'), verify=False )
Creating Gateway Routing Rules
To create a new Gateway Routing Rule you submit a POST to the URI for that resource.
The following example creates a Gateway Routing Rule with the name Rule1, which gateways from H.323, SIP and WebRTC to Microsoft Lync / Skype for Business:
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/gateway_routing_rule/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'name': 'Rule1', 'priority': 50, 'match_incoming_h323': True, 'match_incoming_mssip': False, 'match_incoming_sip': True, 'match_incoming_webrtc': True, 'match_string' : '9(.*)', 'replace_string' : '', 'outgoing_protocol': 'mssip', }) ) print "Created new Gateway Routing Rule:", response.headers['location']
Deleting a Gateway Routing Rule
The following example deletes the Gateway Routing Rule with ID 1:
import requests response = requests.delete( "https://<manageraddress>/api/admin/configuration/v1/gateway_routing_rule/1/", auth=('<user1>', '<password1>'), verify=False )
Deploying a new Conferencing Node
By submitting a POST request to the resource URI for Conferencing Nodes, you can create and deploy a new Conferencing Node onto a server running vSphere ESXi 4.1 or higher.
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/worker_vm/", auth=('<user1>', '<password1>'), verify=False, data=json.dumps({ 'name': 'new_node', 'hostname': 'newnode', 'domain': 'example.test', 'address': '<newnode_ip_address>', 'netmask': '<newnode_ip_mask>', 'gateway': '<ip_gateway_address>', 'password': '<newnode_password>', 'system_location': '/api/admin/configuration/v1/system_location/1/', 'deployment_type': 'VMWARE', 'host': 1, 'host_username': '<vcenter_username>', 'host_password': '<vcenter_password>', 'host_network': 'VM Network', 'host_resource_path': '/<vmware_datacenter>/host/<vmware_host>/Resources', 'vm_cpu_count': '8', 'vm_system_memory': '16384', }) ) print "Created new Conferencing Node:", response.headers['location']
Downloading a Conferencing Node for manual deployment
By submitting a POST request with a deployment_type
of MANUAL
, you can download an OVA file which can be used to deploy a new Conferencing Node onto a host server running vSphere ESXi 5.0 or higher.
Deployment types of MANUAL-ESXI4
and MANUAL-HYPERV2012
can also be used.
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/worker_vm/", auth=('<user1>', '<password1>'), verify=False, stream=True, data=json.dumps({ 'name': 'new_node', 'hostname': 'newnode', 'domain': 'example.test', 'address': '<newnode_ip_address>', 'netmask': '<newnode_ip_mask>', 'gateway': '<ip_gateway_address>', 'password': '<newnode_password>', 'system_location': '/api/admin/configuration/v1/system_location/1/', 'deployment_type': 'MANUAL', 'vm_cpu_count': '8', 'vm_system_memory': '16384', }) ) with open('conferencing_node.ova', 'wb') as handle: for chunk in response.iter_content(10*1024): handle.write(chunk) print "Downloaded Conferencing Node OVA: conferencing_node.ova"
Deploying a Conferencing Node using a VM template and configuration file
You can use a deployment_type
of MANUAL-PROVISION-ONLY
to create a VM template for deployment onto unsupported hypervisors or orchestration layers.
import json import requests response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/worker_vm/", auth=('<user1>', '<password1>'), verify=False, stream=True, data=json.dumps({ 'name': 'new_node', 'hostname': 'newnode', 'domain': 'example.test', 'address': '<newnode_ip_address>', 'netmask': '<newnode_ip_mask>', 'gateway': '<ip_gateway_address>', 'password': '<newnode_password>', 'system_location': '/api/admin/configuration/v1/system_location/1/', 'deployment_type': 'MANUAL-PROVISION-ONLY', }) ) with open('conferencing_node.xml', 'wb') as handle: for chunk in response.iter_content(10*1024): handle.write(chunk) print "Downloaded Conferencing Node provisioning document: conferencing_node.xml"
After the provisioning document has been obtained from the management API as above, it may be injected into the Conferencing Node to be provisioned as follows:
import requests with open('conferencing_node.xml', 'rb') as handle: document = handle.read() response = requests.post( "https://<conferencingnodeaddress>:8443/configuration/bootstrap/", verify=False, headers={'Content-Type': 'text/xml'}, data=document, ) if response.status_code == requests.codes.ok: print "Successfully provisioned Conferencing Node"
Note that this API is available only on Conferencing Nodes created using the MANUAL-PROVISION-ONLY
deployment type.
Uploading a service theme
The following example will create a new theme, upload the theme contents and then configure a VMR to use the theme:
import requests import json import urlparse response = requests.post( "https://<manageraddress>/api/admin/configuration/v1/ivr_theme/", auth=('<user1>', '<password1>'), data=json.dumps({ 'name': 'New theme' }), verify=False) theme_uri = response.headers['location'] theme_path = urlparse.urlsplit(theme_uri).path response = requests.patch( theme_uri, auth=('<user1>', '<password1>'), files={ 'package': open('test_theme.zip', 'rb') }, verify=False) response = requests.patch( "https://<manageraddress>/api/admin/configuration/v1/conference/1/", auth=('<user1>', '<password1>'), data=json.dumps({ 'ivr_theme': theme_path }), verify=False)