Note: this is a draft page documenting the development of the GENI Collector API access.

GENI Collector API

This page details the developmental progress and description of the GENI Collector API access system.

The API is accessed in similar fashion to accessing metric data from a GENI Monitoring DataStore. (ie: /API/data/?q={json})

Examples

Request

Data Request JSON

  {
    eventType: [
      "opsmonitoring:_____",
      ...
    ],
    ts: {
      gte*: #####,        // milliseconds or microseconds
      lt*: #####          // milliseconds or microseconds
    },
    obj: {
      type*: _______,     // string of pollable object time (aggregate, node, interface, etc.)
      id: [
        _______,         // string of either urn or id of a requested target
        ...
      ]
    },
    output: _______      // string of output format type (xml or json). if not supplied, defaults to xml
  }

Note: items denoted with a (*) are required

Example Data Request URL

http://genimondev.uky.edu/API/data/?q={%22ts%22:{%22lt%22:1456162423790000,%22gte%22:1456158823790000},%22obj%22:{%22type%22:%22aggregate%22,%22id%22:[%22ukypks2-ig%22]},%22output%22:%22json%22}

Response

Data Response (XML) [Default]

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <request>
    <url>_____</url>                                                    // the url from which this response was generated
  </request>
  <objects>
    <object urn="_____" id="_____" schema="_____" objectType="_____">   // descriptors of this object   
      <events eventType="_____" units="_____">                          // descriptors of this eventType list
        <event>
          <ts>#####</ts>                                                // timestamp of this event (in milliseconds)
          <v>_____</v>                                                  // value for this eventType at this timestamp
        </event>
        ...
      </events>
    </object>
    ...
  </objects>
</response>

Data Response (JSON)

  [
    {
      "$schema": "http://www.gpolab.bbn.com/monitoring/schema/20151105/data#",
      "description": "ops_monitoring:_____ for _____ of type _____",             // eventType, id, objectType
      "eventType": "ops_monitoring:_____",                                       // eventType
      "id": "_____:_____",                                                       // eventType, id
      "subject": {
        "href": "_____#"                                                         // schema of objectType
      },
      "tsdata": [
        "ts": #####,                                                             // (in milliseconds)
        "v": _____                                                               // depends on the eventType
      ],
      "units": _____                                                             // describes the units fo the eventType
    }
  ]

Reference

Schema

Request JSON

{
  "$schema": "http://json-schema.org/draft-03/schema#",
  "additionalProperties": false,
  "description": "Request Object for GENI Monitoring Collector API.",
  "id": "localhost:9000/schema/request#",
  "name": "request",
  "properties": {
    "$schema": {
      "default": "localhost:9000/schema/request#",
      "description": "The schema of this file.",
      "format": "uri",
      "required": false,
      "type": "string"
    },
    "eventType": {
      "additionalProperties": false,
      "description": "Event types to search for. If this is missing, all of the requested events for target type are returned.",
      "items": {
        "description": "An array holding the GENI IDs of the request targets or a single element 'all'.",
        "required": true,
        "type": "string"
      },
      "required": false,
      "type": "array"
    },
    "obj": {
      "description": "Targets for this request.",
      "properties": {
        "id": {
          "description": "Array holding the GENI urns of the targets of the request.",
          "required": false,
          "type": "array"
        },
        "type": {
          "description": "The type of objects being requested.",
          "required": true,
          "type": "string"
        }
      },
      "required": true,
      "type": "object"
    },
    "output": {
      "description": "Output style requested. Defaults to XML if not specified.",
      "enum": [
        "json",
        "xml"
      ],
      "required": false
    },
    "ts": {
    "description": "Timestamps for request",
    "properties": {
        "gte": {
          "description": "Timestamp for DATA requests indicating the start of the time range in either milliseconds or microseconds. Required for DATA requests.",
          "required": true,
          "type": "number"
        },
        "lt": {
          "description": "Timestamp for DATA requests indicating the end of the time range in either milliseconds or microseconds. Required for DATA requests.",
          "required": true,
          "type": "number"
        },
        "ts": {
          "description": "Timestamp for INFO requests in either milliseconds or microseconds. If missing, defaults to current time.",
          "required": false,
          "type": "number"
        }
      },
      "required": true,
      "type": "object"
    }
  },
  "type": "object"
}