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):

{
    "about":"RRDtool graph JSON output",
    "meta":{
      "start":1489193760,
      "end":1489280160,
      "step":240,
      "legend":["WAN in","WAN out"]
    },
    "Data": [
      [69603.195556,39176.017778],
      [41630.633333,37621.266667],
      [85979.170433,37950.492026],
      [...response truncated...]
    ]
  }

The response "meta" data provides the beginning and end timestamps, the interval between each datapoint, as well as the series labels.

Each entry in the "Data" array provides an array of y-axis values for each series for the current time slot.

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.

Requesting Graph Images

Obtaining PNG or PDF 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".

1. ## 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"
}

1. ## 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}

1. ## 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