ROME REST API

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

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

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 ROME web interface is structured into parent tabs and child tabs.

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

  • Stats:
    • systemQpsStats
    • trunkQpsStats
    • vsxiClusterConfigStatus
  • Routes:
    • routes
    • routeTableGroup
    • jurisdiction
    • jurisdictionProfile
  • Switches:
    • switchproxy
  • Carriers:
    • trunk
    • carrier
  • System:
    •  
  • VSXi control
    • pushVSXiClusterConfig
    • VSXi_route
    • VSXi_routegroup
    • VSXi_routetable
    • VSXi_resource
    • VSXi_resourceblock
    • VSXi_digit_mapping_index
    • VSXi_digit_mapping
    • VSXi_subscriber
    • VSXi_virtualip
    • VSXi_serviceport
    • VSXi_systemConfiguration

Note: All VSXi-control related commands must specify a clusterID argument. Example:

curl -u $user:$pass -X GET -k -o file.xml "https://ipaddress:8888/ROME/webresources/hrs/download/VSXi_route?clusterID=1"

The ROME REST API supports XML, JSON and for specific tables CSV.  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}

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 route entry 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.

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 routeCSV CSV
GET download routeTableGroup XML/JSON
GET download blockedRoutes XML/JSON
GET download trunk XML/JSON
GET download switchProxy XML/JSON
GET download carrier XML/JSON
GET download jurisdiction XML/JSON
GET download jurisdictionCSV CSV
GET download jurisdictionProfile XML/JSON
GET download jurisdictionTypeName XML/JSON
GET download configFile Proprietary
GET download systemConfiguration Proprietary
GET downloadLarge systemRateParameters XML/JSON
GET downloadLarge hardwareConfiguration Zip SDC
       
       
POST update route XML/JSON/CSV
POST update routeCSV XML/JSON
POST update blockedRoutes XML/JSON
POST update switchProxy XML/JSON
POST update carrier XML/JSON
POST update jurisdiction XML/JSON
POST update jurisdictionCSV XML/JSON
POST update jurisdictionProfile XML/JSON
POST update jurisdictionTypeName XML/JSON
DELETE delete route XML/JSON
DELETE delete routeCSV CSV
DELETE delete switchProxy XML/JSON
DELETE delete trunk XML/JSON
DELETE delete carrier XML/JSON
DELETE delete jurisdiction XML/JSON
DELETE delete jurisdictionCSV CSV
DELETE delete jurisdictionProfile XML/JSON
DELETE delete jurisdictionTypeName 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

Download

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

Update

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

Delete

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

Query

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

or

curl -u USERNAME:PASSWORD -X GET -o DMT.xml
             "https://SERVER_IP:8888/ROME/SSConfig/hrs/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/ROME/SSConfig/hrs/webresources/stats/realtime"
 

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 ROME the whole file is validated and if any error is found, the process is aborted and no changes are done to the system table.

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.

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
Like1 Follow
  • 1 Likes
  • 3 mths agoLast active
  • 85Views
  • 2 Following