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.

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 VSXi 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/hrs/<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 ROME 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.

Upload

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

Query specified table using the specified query string. HTTP GET.

Stats 

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

System

Downloads system status or files.  HTTP GET.

Tables

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"

Data Input and Ouput

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.

List of Commands

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.

Examples

Download

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

or

curl -u USERNAME:PASSWORD -X GET -k -o jurisdictionCSV.zip
            "https://SERVER_IP:8888/ROME/webresources/hrs/download/jurisdictionCSV?tableID=1"

Update

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

Delete

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

Query

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

or

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

Error Codes

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.

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.