[[PageOutline]]

''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"
}
}}}