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/hrs/<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 DELETE.

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-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/hrs/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

 

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
Like Follow
  • 7 mths agoLast active
  • 110Views
  • 3 Following