[[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''

==== Valid Metric Request Object Types ====
 * aggregate
 * node
 * interface
 * vlan
 * check | experiment

==== Valid Metric eventTypes per Object Type ====
 * aggregate
    * is_available
    * routable_ip_available
    * raw_pc_available
    * nodelogin
 * node
    * cpu_util
    * mem_used_kb
    * swap_free
    * disk_used_max_part
    * num_vms_allocated
    * is_available
 * interface | vlan
    * rx_bps
    * tx_bps
    * rx_pps
    * tx_pps
    * rx_eps
    * tx_eps
    * rx_dps
    * tx_dps
 * interface only
    * tx_power
    * tx_freqency
    * wmx_noc
 * experiment | check
    * ping_rtt_ms
    * is_stitch_path_available

==== Example Request URL ====

{{{
https://genimon.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 ====

{{{
  {
    infoType: _____,     // the type of info requested (simple or detailed)
    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
  }
}}}

''Note on infoType:
            * '''simple''' - Returns a list with the object details
            * '''detailed''' - Returns a list with the object details as well as any child objects associated to said object

==== Valid Info Request Object Types ====
 * opsconfig | configstore
 * aggregate
 * sliver
 * node
 * link
 * interface
 * vlan
 * authority
 * slice
 * checkstore | externalcheckstore
 * check | experiment

==== Example Request URL ====

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

=== Response ===

==== Response Format (XML) [Default] ====

{{{
  <?xml version="1.0" encoding="UTF-8"?>
  <response>
    <request>
      <url>
        _____
      </url>
    </request>
    <objects>
      <______>
        <______>______</_____>
        ...
      </_____>
      ...
    </objects>
  </response>
}}}

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

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

= Example Queries =

 * Get a list of aggregates in JSON format (SImple meaning just the aggregate itself, not its children)

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"type":"aggregate"},"output":"json","infoType":"simple"}
}}}

 * Get a list of aggregates in XML format

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"type":"aggregate"},"output":"xml","infoType":"simple"}
}}}

 * Get information about a single aggregate by short name in JSON format

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"id":["max-ig"],"type":"aggregate"},"output":"json","infoType":"simple"}
}}}

 * Get information about a single aggregate by short name in XML format

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"id":["max-ig"],"type":"aggregate"},"output":"xml","infoType":"simple"}
}}}

 * Get information about a single aggregate by URN in JSON format

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"id":["urn:publicid:IDN+instageni.maxgigapop.net+authority+cm"],"type":"aggregate"},"output":"json","infoType":"simple"}
}}}

 * Get information about a single aggregate by URN in XML format

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"id":["urn:publicid:IDN+instageni.maxgigapop.net+authority+cm"],"type":"aggregate"},"output":"xml","infoType":"simple"}
}}}

 * Get event information about an aggregate

{{{
http://genimon.uky.edu/API/data/?q={"obj":{"id":["max-ig"],"type":"aggregate"},"output":"xml","ts":{"gte":1456260153962,"lt":1456263753962}}
}}}

 *  Just is_available for an aggregate in XML format

{{{
http://genimon.uky.edu/API/data/?q={"eventType":["is_available"],"obj":{"id":["max-ig"],"type":"aggregate"},"output":"xml","ts":{"gte":1456345005000,"lt":1456348605000}}
}}}

 *  Just is_available for an aggregate in JSON format

{{{
http://genimon.uky.edu/API/data/?q={"eventType":["is_available"],"obj":{"id":["max-ig"],"type":"aggregate"},"output":"json","ts":{"gte":1456345005000,"lt":1456348605000}}
}}}

 *  List all slivers in XML

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"type":"sliver"},"output":"xml","infoType":"simple"}
}}}

 *  Info about a single sliver in json

{{{
http://genimon.uky.edu/API/info/?q={"obj":{"id":["lan.sdn.uky.edu_sliver_38337"],"type":"sliver"},"output":"json","infoType":"detailed"}
}}}