Graph API
The rXg records a great deal of instrumentation data as it operates. The data is stored in a combination of round-robin database files (RRD files) as well as the standard database, depending on the element of the system being instrumented. The rXg makes this data available through the admin console in the form of interactive graphs, as well as through the Graph API in the form of JSON or XML data points. Graphs may also be retrieved in PNG or PDF format.
Authentication:
All calls to the Graph API must be accompanied by an API key which may be obtained by clicking the show link next to an Admin in the administration console.
Extracting Data points
The database entries consist of timestamp values and the recorded value at the given time. These data points may be extracted using the Graph API.
If there is an existing Graph object stored in the database (created under the Archives::Reports subviews) which references the desired graphables, the Graphs ID may be used to simplify the parameters that must be sent in the request.
If there is no pre-existing Graph object, the necessary parameters may be assembled manually and included in the request.
Endpoint: /admin/graphs/graph_export.[json|xml]
cURL example:
curl -i -X POST -H 'Content-Type: application/json' -d '{ "graph": { "id":"1", "type":"NetworkGraph" } }' https://rxg.dns/admin/graphs/graph_export.json?api_key=rJ8FygG...
Example Request: (no pre-existing graph):
{
"graph":
{
"aggregate":"false",
"graph_time":
{
"past_time":"1",
"past_time_unit":"months"
},
"graphables":
[
{"id":"1", "model":"UsagePlan"},
{"id":"2", "model":"UsagePlan"},
{"id":"3", "model":"UsagePlan"}
],
"grouped_by":"week",
"target":"revenue",
"type":"AccountingGraph"
}
}
Example Request: (pre-existing graph):
{
"graph":
{
"id":"4",
"type":"AccountingGraph"
}
}
Note: Clicking on the title of any graph within the admin console and inspecting the resulting URL in the address bar is an easy way to determine the request parameters that comprise that graph.
Example Response (line graph):
[
{
"key": "Uplink in",
"values": [
{
"x": 1752772800,
"y": 1914221.4393
},
{
"x": 1752773040,
"y": 1892728.4784
},
[... additional datapoints ...]
],
"area": true
},
{
"key": "Uplink out",
"values": [
{
"x": 1752772800,
"y": 391642.1333
},
{
"x": 1752773040,
"y": 550121.9461
},
],
"area": true
},
[... additional series ...]
]
Example Response (Bar Graph)
[
{
"values": [
{"x":"Sunday","y":24.0},
{"x":"Monday","y":14.0},
{"x":"Tuesday","y":12.0},
{"x":"Wednesday","y":12.0},
{"x":"Thursday","y":20.0},
{"x":"Friday","y":30.0},
{"x":"Saturday","y":16.0}
],
"key":"Basic",
"color":"#01545A"
},
{
"values": [
{"x":"Sunday","y":10.0},
{"x":"Monday","y":16.0},
{"x":"Tuesday","y":18.0},
{"x":"Wednesday","y":12.0},
{"x":"Thursday","y":8.0},
{"x":"Friday","y":20.0},
{"x":"Saturday","y":12.0}
],
"key":"Enhanced",
"color":"#017351"
}
]
The response array includes an object for each series. Each object contains a "key" and "values" key. The values key contains an array of objects each with an "x" and "y" value for every datapoint in the graph.
The x value may be either an integer timestamp in the unix epoch format (e.g. 1752773040) or in the case of a bar graph, it may be a string containing the label for that x coordinate (e.g. "Sunday").
NOTE that as of build 16.202 the format of both line and bar graphs has been unified to the structure shown above. Previously, line graphs which source their data from an RRD file would output their data using an RRD-specific structure, while bar graphs used the structure above.
Requesting Graph Images, PDF or CSV exports
Obtaining PNG, PDF or CSV output is a 3-step process. Upon requesting an image, the system will launch a background process to generate the data, and returns two URLs: one to check on the status of the file generation, and another to retrieve the generated file.
The request parameters are almost identical to the parameters that would be sent to export the datapoints, but also includes the desired image format "image_format". Valid image format values are "png_2k", "png_4k", "pdf", and "csv".
- ## Generate the file
Endpoint: /admin/graphs/generate_graph_file.[json|xml]
Example Request: (no pre-existing graph):
{
"graph"=>
{
"aggregate"=>"false",
"graph_time"=>
{
"past_time"=>"1",
"past_time_unit"=>"months"
},
"graphables"=>
[
{"id"=>"1", "model"=>"Policy"},
{"id"=>"2", "model"=>"Policy"},
{"id"=>"3", "model"=>"Policy"}
],
"grouped_by"=>"day",
"target"=>"bits",
"type"=>"NetworkGraph"
},
"image_format" => "png_2k"
}
Example Request: (pre-existing graph):
{
"graph"=>
{
"id"=>"4",
"type"=>"AccountingGraph"
},
"image_format" => "png_2k"
}
Example Response:
{
"status_url":"https://gw1.company.com/admin/menu/check_tmp_file.json?filename=rxg.local_NetworkGraph_Uplink_2K_2017-03-14_15-44-50.png",
"download_url":"https://gw1.company.com/admin/menu/send_tmp_file.json?filename=rxg.local_NetworkGraph_Uplink_2K_2017-03-14_16-44-50.png",
"filename":"rxg.local_NetworkGraph_Uplink_2K_2017-03-14_16-44-50.png"
}
- ## Check the Status
Endpoint: https://gw1.company.com/admin/menu/check\_tmp\_file.json?filename=rxg.local\_NetworkGraph\_Uplink\_2K\_2017-03-14\_16-44-50.png (obtained from previous call)
Example Response:
{
"exists":true,
"download_url":"https://gw1.company.com/admin/menu/send_tmp_file.json?filename=rxg.local_NetworkGraph_Uplink_2K_2017-03-14_16-44-50.png"
}
OR
{"exists":false}
- ## Download the file
Endpoint: https://gw1.company.com/admin/menu/send\_tmp\_file.json?filename=rxg.local\_NetworkGraph\_Uplink\_2K\_2017-03-14\_16-44-50.png (obtained from previous call)
Exported graph is returned as a file download
