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.

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 NSS 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/ROME/webresources/nss/<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.

Replace

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

Stats

Downloads systems statistics.

Tables

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)

Data Input and Ouput

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.

Examples

Download policies (aka Authorized ANI) table:

• curl -u xxx:xxx -X GET -k -o ani.zip "https://localhost:8888/ROME/webresources/nss/download/authorizedANI?operatorID=1&format=json"

Update policies:

• curl -u xxx:xxx -X POST -k -T ani.zip "https://localhost:8888/ROME/webresources/nss/update/authorizedANI?operatorID=1&format=csv"

Delete policies:

• curl -u xxx:xxx -X DELETE -k -T ani.zip "https://localhost:8888/ROME/webresources/nss/delete/authorizedANI?operatorID=1&format=csv"

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"

Error Codes

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.

Using the "all" wildcard against the Policies table.

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

REST Example:

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

SOAP Example: