Skip to end of banner
Go to start of banner

opCharts REST API Reference

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

General

All requests lists below are JSON requests.  HTML requests will work for these URL's but may return different data.  To guarantee a json request append .json to the end of the url (but not the query string).

CodeDescription
200Successful request. Body will Contain JSON object
401Authentication required

 

Authentication

Authentication is required to access all methods listed below.

POST login (authenticate)

POST /omk/opCharts/login

Authenticate to opCharts. 

Request

ParameterDescription
usernameThe username to authenticate with
passwordThe password for the user

Successful Response

A cookie is created and sent with the response.  This must be saved and passed with all requests below.  

Nodes

Nodes are gathered from the NMIS installation on the existing server.  Each node has a list of resources.  Each resource can either be indexed or non-indexed.  If non-indexed each resource contains a list of datasets (which are individual data points over time, eg. avgbusy5).  If indexed, the resource contains an array, each element in that array contains datasets.

GET nodes (fetch list of nodes)

GET /omk/opCharts/nodes/

Retrieves the nodes available to opCharts.  No parameters are accepted.

Successful Response

Returns an array of strings containing the node names 

[
  "odin",
  "sparkle",
  "maverick",
]

 

GET node resources (fetch resources for a single node)

GET /omk/opCharts/nodes/[node]/resources/

Retrieves all resources for the specified node.  A resource is required when requesting specific datasets or indexed datasets.

Successful Response

Returns an array of resource objects. Each resource object has a value it can be identified by(which can be used in later requests) and a url that the resource value can be appended to in order to fetch information about this resource and it's name which can be displayed to users.

[
  {
    value: "nodehealth",
    url: "/omk/opCharts/nodes/asgard/resources",
    name: "nodehealth"
  },
  {
    value: "mib2ip",
    url: "/omk/opCharts/nodes/asgard/resources",
    name: "mib2ip"
  },
  {
    value: "interface",
    url: "/omk/opCharts/nodes/asgard/resources",
    name: "interface"
  },
  ....
]

GET node resource datasets (fetch datasets for a single node & resource)

GET /omk/opCharts/nodes/[node]/resources/[resource]/

Retrieves all datasets for the specified node & resource.

Successful Response

An array of dataset objects. Each dataset object lists it's resource, the value it can be identified by, a url that the value can be appended to (if not ending in .json), tokens used for searching and it's name which can be used for displaying to users.

Non-indexed:

[
  {
    indexed: "",
    resource_id: "mib2ip",
    value: "ipInAddrErrors",
    url: "/omk/opCharts/nodes/asgard/resources/mib2ip/datasets",
    tokens: [
      "ipInAddrErrors",
      "mib2ip"
    ],
    name: "ipInAddrErrors"
  },
  ...
]

If a dataset is indexed it must be accessed through one of the indexes provided by the resource.  This list can be found using the url listed in the dataset object.

Indexed: 

[
  {
    indexed: "1",
    resource_id: "interface",
    value: "ifInOctets",
    url: "/omk/opCharts/nodes/asgard/resources/interface/indicies.json",
    tokens: [
      "ifInOctets",
      "interface"
    ],
    name: "ifInOctets"
  },
  ...
]

GET node resource indexes (fetch indexes for a node resource)

GET /omk/opCharts/nodes/[node]/resources/[resource]/indicies.json

Retrieve all indexes available from a resource.  This is only required if the dataset you wish to load is indexed.

Successful Response

Returns a hash, with the name of the resource.  A datum array of index objects, these hold the data you are likely looking for.  The value attribute holds the identifier for this object.  Name is the attribute which can be displayed to users.

The list of datasets available for the specified resource along with the list of indexes create an N x M matrix of possible datasets.

{
  name: "interface",
  datum: [
    {
      resource_id: "interface",
      value: "2",
      url: "/omk/opCharts/nodes/asgard/resources/interface/datasets",
      tokens: [
        "WAN/DSL",
        "FastEthernet0/1",
        "2"
      ],
      name: "WAN/DSL -- FastEthernet0/1 -- 2"
    },
    {
      resource_id: "interface",
      value: "1",
      url: "/omk/opCharts/nodes/asgard/resources/interface/datasets",
      tokens: [
        "Opmantek LAN",
        "FastEthernet0/0",
        "1"
      ],
      name: "Opmantek LAN -- FastEthernet0/0 -- 1"
    }
  ],
  header: "interface"
}

Data

GET node resource dataset (fetch data for a single dataset from a node resource)

GET /omk/opCharts/data_model_view/new?requestData=[JSON object]

Request data from a dataset.  There are 2 basic ways to request data.

  1. Request NMIS dataset information for a specific dataset from an RRD file (nmis_rrd)
  2. Request NMIS graph information, this provides the same data that is displayed in NMIS graphs and are defined by nmis Graph-*.nmis files (nmis_graph)

 

 The request structure is not simple. The required inputs are resource, dataset, possibly index.  

Required Parameters

     
requestData{   
 model_view  "graph", no other options supported at this time
 parameters{ #holds general parameters that might be used to gather several datasets for the same graph
  time_period "specific_time" or "time_difference. When specific_time is specified the times are used as-is. When time_difference is specified, the times given are subtracted, that period is then applied to the current time being the stop_date and start_date = current_time - period
  start_date Any parse-able date, eg "16-May-2014 09:24:56", usage specified by time_period
  end_date Any parse-able date, eg "23-May-2014 09:24:56", usage specified by time_period
  }  
 options{}  
 dataset{  
  name can be anything, unused but will be returned back in the response
  type "nmis_rrd" or "nmis_graph". nmis_rrd will provide data directly as it is in the RRD files. nmis_graph will provide data after running it through the manipulations done by the NMIS graph
  data_source Normally "local_nmis". Can also be other MySQL datasource if configured, then the name property of the data_source that is required.
  parameters{ 
   nodemaps to a node found using GET node
   graph_type

nmis_rrd: maps to a resource found using Get Node Resources (value attribute, which is the ID)

nmis_graph: maps to the name of the graph if not indexed, maps to the same as nmis_rrd if indexed

   resource_indexIf the resource is indexed, the index of the resource required
   index_graph_type

Only used if the resource is indexed:

 nmis_rrd:

nmis_graph: the name of the graph

   fieldOnly used for nmis_rrd: maps to the dataset required found using GET node resource datasets (value attribute of desired dataset)
   axis0 or 1, the axis the dataset will group itself into, usually 0
   } 
  options{ 
   datasetTitleThe title the dataset will return with itself
   } 
  }  
 }   

Request  Example

"requestData": {
  "parameters": {
    "time_period": "time_difference",
    "end_date": "23-May-2014 11:54:20",
    "start_date": "16-May-2014 11:54:20"
  },
  "options": {},
  "dataset": {
    "parameters": {
      "node": "asgard",
      "type": "nmis_rrd",
      "graph_type": "nodehealth",
      "resource_index": "",
      "index_graph_type": "",
      "field": "avgBusy1",
      "axis": "0"
    },
    "name": "auto_generated",
    "type": "nmis_rrd"
  },
  "model_view": "graph"
}

Successful Response

A successful response will be a hash with 2 objects.  The requestObject that was submitted along with a responseObject : 

{
  "requestData": {
    ... <snip, same as above >...
  },
  "replyData": {
    "options": {
      "subtitleText": null,
      "titleText": null,
      "yAxis1TitleText": null,
      "plotBands": [],
      "yAxis0TitleText": null
    },
    "min": null,
    "stacking": null,
    "max": null,
    "meta_data": {
      "time_start": 1400206204,
      "start_date_input": "2014-05-16 12:10:04",
      "end_date_input": "2014-05-23 12:10:04"
    },
    "data": [
      {
        "yAxis": 0,
        "color": null,
        "stack": null,
        "name": "avgBusy1",
        "type": null,
        "data": [
          [
            1400206500000,
            null
          ],
          [
            1400206800000,
            null
          ],
          [
            1400571000000,
            6
          ],
          [
            1400571300000,
            6.99308580333333
          ],
          [
            1400571600000,
            9.98057514
          ],
          [
            1400571900000,
            8.00908836666667
          ],
          [
            1400572200000,
            6.01230244666667
          ],
          [
            1400572500000,
            3.02188843
          ],
          [
            1400572800000,
            2.00550849666667
          ],
        ]
      }
    ]
  }
}

For nmis_rrd, the important data is held in replyData->data->[0]->data, this is an array holding [ time, value ].  Time is in Javascript time format (and not unix epoch, to get this simply divide by 1000 ).

For nmis_graph, the data is almost the same but there may be more than 1 entry in replyData->data.  There will be one per dataset that is on the graph, for example avgbusy1, avgbusy5.  

If there is no data for that time in NMIS null will be returned.

  • No labels