[[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})

== Metric Data ==

=== Request ===

==== Request Format ====

{{{
  {
    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 Request URL ====

{{{
http://genimondev.uky.edu/API/data/?q={"obj":{"id":["pks2.sdn.uky.edu_node_pc1"],"type":"node"},"output":"json","ts":{"gte":1456260153962,"lt":1456263753962}}
}}}

=== Response ===

==== Response Format (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>
}}}

==== Response Format (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
    },
    ...
  ]
}}}

== Object Information ==

=== Request ===

==== Request Format ====

{{{
  {
    eventType: [
      "opsmonitoring:_____",
      ...
    ],
    ts: {
      ts: #####,         // milliseconds or microseconds, defaults to now() if omitted
    },
    obj: {
      type*: _______,     // string of object type  (aggregate, node, interface, etc.)
      id: [
        _______,         // string of either urn or id of a requested target, returns all if omitted
        ...
      ]
    },
    output: _______      // string of output format type. currently only json for info requests
  }
}}}

==== Example Request URL ====

{{{
http://genimondev.uky.edu/API/info/?q={"obj":{"id":["pks2.sdn.uky.edu_node_pc1"],"type":"node"},"output":"json"}
}}}

=== Response ===

==== Response Format (JSON) ====

{{{
  [
    {
      _____: _____,          // These will be fields specific to the type of object requested
      ...
    },
    ...
  ]
}}}

==== Response Format (XML) ====

''Note: This is currently in the debugging stages, but will resemble the JSON format just using XML structures