VSXi REST API

 

The VSXi REST API allows you to manage VSXi systems in a simple, programmatic way using conventional HTTP requests. Most of the functionality that you are familiar with in the VSXi GUI is also available through the API, allowing you to script the complex actions that your situation requires.

The API documentation will start with a general overview and then break down the different components. To access the VSXi REST API,  basic HTTP knowledge is necessary: how an HTTP request is sent as {method url}, how to attach a file as input and save output into a file.

Authentication

User authentication is done on each request using basic authentication. User has to input a valid GUI/API username/password and embed that in HTTPS basic authentication header.

All requests made to the VSXi follow a similar format, with user authentication performed on each HTTP request.

Syntax

The syntax for REST is as follows:

curl -u $user:$pass -X $METHOD -k -$FLAG file.xml
            https://SERVER_IP:8888/SSConfig/webresources/<action>/{table}?{format=xml/json}

 

In the following sections we go into further detail on actions and tables.

HTTP Methods

The basic supports the following HTTP methods:

• GET: For downloads, queries and stats commands.
• POST: For inserts and changes.
• DELETE: For deletions.

In combination with the HTTP method, the VSXi REST API defines several actions described below. Each action supports a specific HTTP method.

Actions

Download

Downloads data from the specified table. HTTP GET.

Update

Updates entries in the specified table. If the entry is not currently in the table this action functions as an insert. HTTP POST.

Delete

Deletes entries from the specified table. HTTP DELETE.

Upload

Uploads data in a XML file to the server and replaces the data in a specified table. HTTP POST.

Note: A replace is a wipe and insert operation. The large counterpart action is replaceLarge.

xxxxLarge

Commands that have “Large” as part of operation name are used to update, replace, delete or download data in zipped XML (binary) format. HTTP POST.

These actions are:

• updateLarge
• downloadLarge
• deleteLarge
• replaceLarge

Query

Query specified table using the specified query string. HTTP GET.

Stats 

Downloads real-time stats from specified table. HTTP GET.

System

Downloads system status or files.  HTTP GET.

Tables

The VSXi web interface is structured into parent tabs and child tabs. There are eight parent tabs: Monitoring, Trace, Routes, Resources, Digit Mappings, Service Ports, App Servers and System. In the scope of this document a table is defined as the different sub-tabs available on the system. For example, the Resources parent tab has the following tables: Resources, Registrar, Blocked Resources, SIP Profiles, Cause Code Profiles, Stop Route Profiles, SMC Profiles, SMC Data Files and CAC Profiles.

The following tables are supported via API. Tables are listed in the familiar parent-child structure. In parenthesis you will find the web UI reference in parent > child tab format. (e.g. Resources > Resources).

• Monitoring:
  • active_calls (Monitoring > Active Answered Calls)
  • realtime (Monitoring > System Stats)
  • resource (Monitoring > Resource Stats)
  • resource_detail (Monitoring > Real-Time Stats)
  • sip_stats (Monitoring > SIP Stats)
  • sub_stats
• Routes:
  • route (Routes > Routes)
  • routegroup (Routes > Route Groups)
  • routetable (Routes > Route Table)
• Resources:
  • cac_index (Resources > CAC Profies)
  • resource (Resources > Resource)
  • resourceblock (Resources > Blocked Resources)
  • smcDataFile (Resources > SMC Data Files)
  • subscriber Resources > Registrar)
• Digit Mappings:
  • digit_mapping (Digit Mappings > Digit Mappings)
  • digit_mapping_index (Digit Mappings > Digit Mapping Table)
• Service Ports:
  • serviceport (Service Ports > Service Ports)
  • serviceport_certificates
  • media_server_profile (Service Port > Media Server Profiles)
  • virtualip
• App Servers:
  • media_server (App Servers > Media Servers)
• System:
  • hardwareConfiguration (System > Advanced: Save Hardware Info)
  • systemConfiguration (System > Save Config)
  • users ( System > Users)

Data Input and Ouput

The VSXi REST API is an evolution of the VSXi legacy SOAP/Web Services API. By default, if not specified, data will be downloaded or received in XML format. You can use the format parameter within the URL to specify the desired data format.

?{format=xml/json}

While XML/JSON are widely supported some tables or actions support CSV and plain text.

On any data input operation (UPDATE, DELETE, UPLOAD, REPLACE) you must submit the the entire payload. That is all XML/JSON elements that correspond to the table. All fields are required and omitting fields will result in an error. As an example if you are updating one field in the Resource table, you need to submit all fields not just the key element and the field being changed.  The best common practice is to download, edit and upload the file.

While files are most commonly used it is also possibly to send serial data with the full XML/JSON content if desired.

This is an example schema of a resource input file.

         "name" : "Example",
         "companyName" : "Example",
         "trunkId" : 1,
         "sgId" : 0,
         "capacity" : 50,
         "cpsLimit" : 5,
         "node" : [ {
            "fqdn" : "10.1.1.2",
            "netmask" : 32,
            "capacity" : 46,
            "cpsLimit" : 5,
            "cacProfileId" : 0
         }, {
            "fqdn" : "10.1.1.3",
            "netmask" : 32,
            "capacity" : 46,
            "cpsLimit" : 5,
            "cacProfileId" : 0
         } ],
         "rtid" : 0,
         "ingress1" : {
            "match" : "1",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "ingress2" : {
            "match" : "all",
            "action1" : "prepend",
            "digits1" : "1",
            "action2" : "none",
            "digits2" : ""
         },
         "egress1" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "egress2" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "outboundANI" : "pass",
         "techPrefix" : "default",
         "rnIngress1" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "rnIngress2" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "rnEgress1" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "rnEgress2" : {
            "match" : "all",
            "action1" : "none",
            "digits1" : "",
            "action2" : "none",
            "digits2" : ""
         },
         "codecPolicy" : "transparent",
         "srtpEnable" : "disable",
         "srtpSize" : 80,
         "srtpDtls" : "disable",
         "groupPolicy" : "top_down",
         "dtid" : 1,
         "t38" : "enable",
         "rfc2833" : "enable",
         "payloadType" : 101,
         "tos" : "B8",
         "svcPortIndex" : 1,
         "radiusAuthGrpIndex" : 0,
         "radiusAcctGrpIndex" : 0,
         "lnpGrpIndex" : 1,
         "lnpEnhancedGrpIndex" : 0,
         "stiASGrpIndex" : 0,
         "stiVSGrpIndex" : 0,
         "cnamGrpIndex" : 0,
         "ersGrpIndex" : 0,
         "maxCallDuration" : 10800,
         "minCallDuration" : 0,
         "noAnswerTimeout" : 120,
         "noRingTimeout" : 30,
         "causeCodeProfile" : 0,
         "stopRouteProfile" : 0,
         "paiAction" : "Disable",
         "paiString" : "5555555013",
         "inheritedGenericHeader" : "",
         "outSMCProfileId" : 0,
         "stiIngressAuthentication" : "none",
         "stiIngressAuthFailBehavior" : "passthru",
         "stiEgressIdHdrTreatment" : "no-hdr",
         "stiIngressVerification" : "disable",
         "stiEgressVerifyFailBehavior" : "passthru"
      } ]
   }

 

List of Commands

Having an understanding of the supported HTTP methods, system tables and actions the following table provides a list of the possible "commands" that can be issued via API and supported data format.

HTTP Method	Action	Table	Format
GET	download	route	XML/JSON/CSV
GET	download	routegroup	XML/JSON
GET	download	routetable	XML/JSON
GET	download	resource	XML/JSON
GET	download	resourceblock	XML/JSON
GET	download	digit_mapping_index	XML/JSON
GET	download	digit_mapping	XML/JSON
GET	download	subscriber	XML/JSON
GET	download	media_server_profile	XML/JSON
GET	download	media_server	XML/JSON
GET	downloadLarge	route	Zip XML/JSON/CSV
GET	downloadLarge	subscriber	Zip XML/JSON
GET	downloadLarge	digit_mapping	Zip XML/JSON
GET	downloadLarge	systemConfiguration	Zip SDC
GET	downloadLarge	hardwareConfiguration	Zip SDC
GET	downloadLarge	smcDataFile	Zip CSV
POST	update	route	XML/JSON/CSV
POST	update	routegroup	XML/JSON
POST	update	routetable	XML/JSON
POST	update	resource	XML/JSON
POST	update	resourceblock	XML/JSON
POST	update	digit_mapping_index	XML/JSON
POST	update	digit_mapping	XML/JSON
POST	update	subscriber	XML/JSON
POST	update	users	XML/JSON
POST	updateLarge	route	Zip XML/JSON/CSV
POST	updateLarge	subscriber	Zip XML/JSON
POST	updateLarge	digit_mapping	Zip XML/JSON
DELETE	delete	route	XML/JSON/CSV
DELETE	delete	routegroup	XML/JSON
DELETE	delete	routetable	XML/JSON
DELETE	delete	resource	XML/JSON
DELETE	delete	resourceblock	XML/JSON
DELETE	delete	digit_mapping_index	XML/JSON
DELETE	delete	digit_mapping	XML/JSON
DELETE	delete	subscriber	XML/JSON
DELETE	delete	sub_stats	XML/JSON
DELETE	delete	active_calls	XML/JSON/CSV
DELETE	delete	users	XML/JSON
DELETE	deleteLarge	route	Zip XML/JSON/CSV
DELETE	deleteLarge	subscriber	Zip XML/JSON
DELETE	deleteLarge	digit_mapping	Zip XML/JSON
POST	upload	route	XML/JSON /CSV
POST	upload	routegroup	XML/JSON
POST	upload	routetable	XML/JSON
POST	upload	resource	XML/JSON
POST	upload	resourceblock	XML/JSON
POST	replaceLarge	route	Zip XML/JSON/CSV
POST	replaceLarge	routesInRouteTable	Zip XML/JSON/CSV
POST	replaceLarge	subscriber	Zip XML/JSON
POST	replaceLarge	digit_mapping	Zip XML/JSON
POST	replaceLarge	digitMappingsInDigMapTable	Zip XML/JSON
POST	replaceLarge	smcDataFile	Zip CSV
GET	query	route	XML/JSON
GET	query	resource	XML/JSON
GET	query	subscriber	XML/JSON
GET	query	digit_mapping	XML/JSON
GET	query	active_calls	XML/JSON
GET	stats	resource	XML/JSON
GET	stats	realtime	XML/JSON
GET	stats	resource_detail	XML/JSON
GET	stats	media_server	XML/JSON
GET	stats	sub_stats	XML/JSON
GET	stats	sip_stats	XML/JSON
GET	stats	active_calls	XML/JSON/CSV
GET	system	realtime	Text

Examples

Download

curl -u $user:$pass -X GET -k -o file.xml
            "https://SERVER_IP:8888/SSConfig/webresources/download/route"

Update

curl -u $user:$pass -X POST -k -T file.xml
             "https://SERVER_IP:8888/SSConfig/webresources/update/resource"

Delete

curl -u $user:$pass -X DELETE -k -T file.xml
              "https://SERVER_IP:8888/SSConfig/webresources/delete/resource"

Query

curl -u USERNAME:PASSWORD -X GET -o DMT.xml
              "https://SERVER_IP:8888/SSConfig/webresources/query/digit_mapping?queryString=alias like '%TEST%'"

or

curl -u USERNAME:PASSWORD -X GET -o DMT.xml
             "https://SERVER_IP:8888/SSConfig/webresources/query/digit_mapping?queryString=alias%20like%20%27%25TEST%25%27"

Stats

curl -u USERNAME:PASSWORD -X GET -k -o /root/stats.xml
             "https://SERVER_IP:8888/SSConfig/webresources/stats/realtime"

If you prefer sending the payload within the curl command instead of using a file this is an example syntax.

curl -u USERNAME:PASSWORD -X POST -k -H "Content-Type:text/xml" -d '<?xml version="1.0" encoding="UTF-8"?><DigitTranslationList><DigitTrans><alias>API_Test</alias><tableId>4</tableId><origAni>any</origAni><origAniMinLength>0</origAniMinLength><origAniMaxLength>40</origAniMaxLength><origDnis>555</origDnis><origDnisMinLength>0</origDnisMinLength><origDnisMaxLength>40</origDnisMaxLength>
<transAni>5555551234</transAni><transDnis></transDnis><aniAction>all</aniAction><dnisAction>passthrough</dnisAction></DigitTrans></DigitTranslationList>' "https://SERVER_IP:8888/SSConfig/webresources/update/digit_mapping"

Query Table Parameters

Querying a table allows you to download just a portion of the content you are interested in instead of the entire table. This is the list of table parameters currently supported:

resource	route	digit_mapping
alias	alias	alias
allow_directMedia	digit_match	table_id
cause_code_profile_id	end_tod	oani
CNAME_group_index	group_id	odnis
codec_policy	max_len	tani
company_name	min_len	tdnis
cps_limit	policy
digit_trans_id	resource_id_1
direction	resource_id_2
DNC_group_index	resource_id_3
ERS_group_index	resource_id_4
LNP_group_index	resource_id_5
max_call_duration	resource_id_6
no_answer_timeout	resource_id_7
no_ring_timeout	resource_id_8
option_poll	start_tod
pai_action	table_id
pai_string
RADIUS_acct_group_index
RADIUS_auth_group_index
service_port_index
service_state
sip_profile_index
source_address
stop_route_profile_id
table_id
tech_prefix
trunk_id
egress_smc_profile_id
srtp_enable
sti_ingress_authentication
sti_ingress_verification
sti_egress_id_hdr_treatment
STI_AS_group_index
STI_VS_group_index
nat_peering

Error Codes

This paragraph lists codes returned by VSXi server in response to various requests. Each return message has the return code and text message that describes the code.

Code	Associated Message	Description
200	200 OK	General OK response.
	200 OK - uploadXmlFile success.	File upload was OK.
300	Finished With Errors	File was uploaded but some items failed validation and were discarded. Valid items were processed successfully.
400	400 fail - invalid table specified: + requested table name.	Invalid table name.
		Invalid table name.
	400 fail - validation exception	XML validation error.
	400 fail - digit match can not be empty	Digit match has to be specified for RouteLookUp
	400 – failed	Other types of errors (exception)
401	401 Fail - User Not Authorized: Invalid username or no read/write permissions.	User is not authorized or doesn't have permissions
	401 Fail - User Not Authorized: invalid user password	User password is invalid.
402	402 Fail - This action is not allowed while system is in Load-Balance Slave mode	No configuration changes are allowed on slave servers data can only be dowloaded

 

When data is uploaded to the VSXi server in plain-text the whole file is validated and if any error is found, the process is aborted and no changes are done to the system table.

In case when “Large” commands are used with compressed (zipped) data, if an error is found in one entry (XML element), that entry is thrown away and error is logged to the user log file. However, the process continues. For example, if one route is found to be invalid, it’s thrown away, but the other routes are processed and stored in DB (updated, replaced, deleted...). In that case the return code is 300, and the message describing the error is “300 Finished With Errors - Validation Errors were detected. Please see User Access Log file for details.”

In both cases errors are logged to User Access Log File that can be found and downloaded in GUI, Trace>User Log tab. Upper box on this page lists all User Log files available for download, and the lower box shows the latest entries in the latest file – user_access.log.

Appendix A - Subscriber Stats Management

Starting in version VSXi-10.5.1.500 it is possible to delete entries in the Subscriber Stats page using SOAP or REST API.

The API request can specify from one or multiple fields to perform the delete. The following fields can be included:

• "username",
• "trunkID",
• "id" (Subscriber ID),
• "userDomain" (Host) or
• "userIp" (Source IP)

Multiple entries are interpreted as an AND operator.

 
Example:

curl -u username:password -X DELETE -k -T sub_stats_delete.xml 'https://testip:8888/SSConfig/webresources/delete/sub_stats'

sub_stats_delete.xml

<?xml version="1.0" encoding="UTF-8"?>
<XBSubStatsList>
<XBSubStats>
<username>8_2216_M</username>
<userDomain>venice-domain-cs2</userDomain>
<id>3-7</id>
<userIp>72.197.139.18</userIp>
<trunkId>00006</trunkId>
</XBSubStats>
<XBSubStats>
<username>8_2215</username>
</XBSubStats>
</XBSubStatsList>

All requests receive a 200 OK.

Appendix B - Subscriber Stats Payload

Full payload response and fiefld defintion for sub_stats endpoint:

• States:
  • Authenticated: Successful registration.
  • Unauthenticated: Registration with pending authentication.
  • Blocked: Endpoint has failed N number of authentication attempts.
  • Pending: Transient state normally indicates waiting for Feature Server/Registrar.
• Trunk ID: Trunk ID associated with the registered user.
• Create Time: Registration instance when the device first registered.
• Username.
• User Domain.
• User IP: Source IP address of registering endpoint.
• User Port: Source Port of registering endpoint.
• ID: Registration ID created by the VSXi for internal tracking purposes.
• NAT: Network Address Translation detection (Yes, No).
• SPID: Origination Service Port ID.
• Protocol:
  • UDP
  • TCP
  • TLS (TLS v1.0, TLS v1.1, TLS v1.2, TLS v1.3).
  • Note: TLS protocol version display added in VSXi-10.7.1.70+.
• Expiration: Calculation of when this registration will expire if the device fails to re-register timely. This was designed for Push Notifications that may not re-register for days or weeks.
• Agent: SIP User-Agent disclosed in the SIP REGISTER.
• PN-PARAM: Push Notifications pn-param per RFC8599.

<XBSubStatsList>
   <XBSubStats>
      <states>AUTHENTICATED</states>
      <trunkId>00013</trunkId>
      <createTime>02-10-2023 17:20:52</createTime>
      <username>2200_06</username>
      <userDomain>sip.sansay.com</userDomain>
      <userIp>192.168.191.98</userIp>
      <userPort>5188</userPort>
      <id>2-1</id>
      <nat>Yes</nat>
      <spid>3</spid>
      <protocol>UDP</protocol>
      <expiration>03-13-2023 07:46:05</expiration>
      <agent>MicroSIP/3.21.3</agent>
      <pn-param></pn-param>
   </XBSubStats>