2

NSS Management via REST API

The NSS REST API allows you to manage NSS systems in a simple, programmatic way using conventional HTTP requests.

The API documentation will start with a general overview and then break down the different components. To access the NSS 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 NSS 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/ROME/webresources/nss/<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.

Deletes entries from the specified table and inserts content in file. HTTP POST.

Stats

Downloads systems statistics.

The NSS web interface is structured into parent tabs and child tabs as illustrated below.  The following tables include REST support, their API name is in parenthesis:

  • Switches > Switches (switchProxy)
  • Switches > SMC Data File (smcDataFile)
  • STI-AS > Policies (authorizedANI)
  • STI-AS > Key Store Confiuration (stiKeystore)
  • STI-AS > Switches (stiSwitchKeyMap)
  • STI-AS > RCD Profiles (stiRcdProfile)
  • STI-VS > Verify DNIS (verifyDNIS)
  • System > Advanced: Backup  (systemConfiguration)
  • Monitoring > Stats: System QPS Stats  (systemQpsStats)
  • Monitoring > Stats: Switch Proxy Stats
  • Monitoring > Stats: Switch Query Stats Stats > (switchQueryStats)
  • Monitoring > Stats: System >  (systemInfo)

The NSS REST API supports XML and JSON. Zipped XML and JSON is also supported to reduce file size upload/download time. 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. While files are most commonly used it is also possible to send serial data with the full XML/JSON content if desired.

Download policies (aka Authorized ANI) table:

Update policies:

Delete policies:

It is also possible to upload unzipped payloads using the optional parameter type=raw. You can use a file or include payload in the POST request. For example:

curl -u "$USER:$PASS" -X POST -k -H "Content-Type:text/xml" -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><STIAuthorizedAnis><XBSTIAuthorizedANI><SbcID>any</SbcID><Otg>any</Otg><Ani>8585551111</Ani><Attestation>A</Attestation></XBSTIAuthorizedANI></STIAuthorizedAnis>' "https://$IP:8888/ROME/webresources/nss/update/authorizedANI?operatorID=1&format=xml&filetype=raw"

This paragraph lists codes returned by NSS 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 – 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

NSS supports specific wildcards to delete more than one entry. New wildcard "all" is exclusive for API and bulk delete provisioning match. The use of this provisioning wildcard is limited to the STI-AS > Policies table. As opposed to "any" that is used for query processing matching, "all" is just for provisioning using a delete action.

Requirement: To delete entries using the "all" wildcard, there MUST be a value of each of these fields: “SbcID”, “Otg” and “Ani”, in which 

  • “Ani” number, “any”, or “all”

  • “SbcID”: number, “any”, or “all”

  • “Otg” : number, “any”, or “all”

Examples:

  • To delete ALL entries:

    •  SbcID = all, Otg = all, Ani = all

  • To delete all entries where SbcID = 1:
    SbcID = 1, Otg = all, Ani = all

  • To delete all entries where Otg = 1:
    SbcID = all, Otg = 1, Ani = all

  • To delete all entries where SbcID = 1 and Otg = 1:
    SbcID = 1, Otg = 1, Ani = all

  • To delete all entries where Ani = 0123456789:
    SbcID = all, Otg = all, Ani = 0123456789

curl -u "$user:$passwd" -X DELETE -k -H "Content-Type:text/xml" -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><STIAuthorizedAnis><XBSTIAuthorizedANI><SbcID>ALL</SbcID><Otg>ALL</Otg><Ani>ALL</Ani><Attestation>C</Attestation></XBSTIAuthorizedANI></STIAuthorizedAnis>' "https://$testip:8888/ROME/webresources/nss/delete/authorizedANI?operatorID=1&format=xml&filetype=raw"

Or attach an xml file (zipped or non-zipped):

curl -u "$user:$passwd" -X DELETE -k -T STIAuthorizedAnis_Operator_1_delete_all_xml.zip "https:/$testip/:8888/ROME/webresources/nss/delete/authorizedANI?operatorID=1&format=xml&filetype=zip"

SOAP Example:

java -jar Sansay_ROME_WS_Client.jar -a$testip -u$user -$passwd delete Downloads/STIAuthorizedAnis_Operator_1_delete_all_xml.zip authorizedANI

<STIAuthorizedAnis>
  <OperatorID>1</OperatorID>
  <AniList>
      <XBSTIAuthorizedANI>
        <SbcID>all</SbcID>
        <Otg>all</Otg>
        <Ani>all</Ani>
      </XBSTIAuthorizedANI>
  </AniList>
</STIAuthorizedAnis>

8 replies

null
    • calvin_ellison
    • 2 yrs ago
    • Reported - view

    GET ... /ROME/webresources/hrs/download/systemQpsStats

    400 Fail - invalid table specified: systemQpsStats

    400 Fail - invalid table specified: switchQueryStats

    What are the correct table names?

    What is the table name for Monitoring > Stats: Switch Proxy Stats?

      • cperez
      • 2 yrs ago
      • Reported - view

      calvin. ellison NSS stats download via API is pending implementation. We will let you know when this is ready. These stats are available in our PSM at the moment.

      • voiceops
      • 2 yrs ago
      • Reported - view

      Carlos Perez  any news about the NSS stats download? Thank you

      • Luis_Felipe_Rodriguez
      • 8 mths ago
      • Reported - view

      Carlos Perez is this API implemented yet? is there any other method to query QPS stats?

    • Jon_Chleboun.2
    • 1 yr ago
    • Reported - view

    Two questions:

    1. In my testing DELETE with the "all" wildcard, the Attestation parameter is also factored into the matching decisions, and that parameter seems to be mandatory as well. E.g. it will only delete the Policies that also match the Attestation level in the request. Is this new? The docs above don't seem to discuss that.
    2. SMC Data Files are handled quite differently, e.g. whatever files are on the server are replaced completely by whatever files are in the zip file uploaded, which could be quite destructive if not understood completely.  Could a brief section on SMC Data File updates be added?
      • cperez
      • 1 yr ago
      • Reported - view

      Jon Chleboun We have a new version coming out that supports a filename parameter. The filename parameter will allow you to work with a specific SMC Data File instead of all of them.

      Next question will be answered shortly.

      • cperez
      • 1 yr ago
      • Reported - view

      Jon Chleboun attestation level is not required, Jon. Here are some examples:

      curl -u "$user:$passwd" -X DELETE -k -H "Content-Type:text/xml" -d '<?xml version="1.0" encoding="UTF-8" standalone="yes"?><STIAuthorizedAnis><XBSTIAuthorizedANI><SbcID>ALL</SbcID><Otg>ALL</Otg><Ani>ALL</Ani></XBSTIAuthorizedANI></STIAuthorizedAnis>' "https://$testip:8888/ROME/webresources/nss/delete/authorizedANI?operatorID=1&format=xml&filetype=raw"

       

      curl -u "$user:$passwd" -X DELETE -k -T STIAuthorizedAnis_Operator_1_delete_all_xml.zip "https:/$testip:8888/ROME/webresources/nss/delete/authorizedANI?operatorID=1&format=xml&filetype=zip"

      <STIAuthorizedAnis>
        <OperatorID>1</OperatorID>
        <AniList>
            <XBSTIAuthorizedANI>
              <SbcID>all</SbcID>
              <Otg>all</Otg>
              <Ani>all</Ani>
            </XBSTIAuthorizedANI>
        </AniList>
      </STIAuthorizedAnis>

      • Jon_Chleboun.2
      • 1 yr ago
      • Reported - view

      Carlos Perez Great to hear on both accounts, new version for individual filenames, and that attestation level is not required for bulk deletes. I am getting errors when I try to delete less than all-all-all (the whole table) when I don't include the attestation parameter, but I'll reach out directly with those.