2

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.

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.

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.

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.

Downloads data from the specified table. HTTP GET.

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

Deletes entries from the specified table. HTTP DELETE.

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.

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 specified table using the specified query string. HTTP GET.

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

Downloads system status or files.  HTTP GET.

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)

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"
      } ]
   }

 

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
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
GET downloadLarge subscriber Zip XML/JSON
GET downloadLarge digit_mapping Zip XML/JSON
GET download virtualip XML/JSON
GET downloadLarge systemConfiguration Zip SDC
GET downloadLarge hardwareConfiguration Zip SDC
       
GET downloadLarge smcDataFile Zip CSV
POST update route XML/JSON
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
POST updateLarge subscriber Zip XML/JSON
POST updateLarge digit_mapping Zip XML/JSON
POST update virtualip XML
DELETE delete route XML/JSON
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
DELETE delete users XML/JSON
DELETE deleteLarge route Zip XML/JSON
DELETE deleteLarge subscriber Zip XML/JSON
DELETE deleteLarge digit_mapping Zip XML/JSON
POST upload route XML/JSON 
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
POST replaceLarge routesInRouteTable Zip XML/JSON
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
GET system realtime Text

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"

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    
     

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.

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.

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>

30 replies

null
    • Jorge_Cuevas
    • 3 yrs ago
    • Reported - view

    How do I use this for update/delete resourceblock, do you have a curl example ?

    I managed to download the resourceblock table with GET, but I can't update it or delete it. I keep getting "400 fail - failed\nnull"

    Do I need to use POST, PUT or GET? the curl example would be great!

    Thanks

      • cperez
      • 3 yrs ago
      • Reported - view

      Jorge Cuevas The guide has been updated with all of this information. Thanks for your feedback.

    • voiceops
    • 3 yrs ago
    • Reported - view

    How do I need to authenticate for POST requests? BasicAuth is not working

      • cperez
      • 3 yrs ago
      • Reported - view

      voiceops were you able to figure this out? BasicAuth (user:pass) is what's supported. We have re-vamped this guide.

    • Jessie_Bryan
    • 2 yrs ago
    • Reported - view

    Just wanted to let you know there's a typo in the "List of Commands" table. 
    The "Query" action should be "query" :)