[[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:_____",
...
],
order: (asc|desc), // string that reverses the order of the metric entries if desc (redundant with "reversed")
reversed: (true|false), // boolean that reverses the order of the metric entries if true (redundant with "order")
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] ====
{{{
_____ // the url from which this response was generated
...
}}}
==== 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] ====
{{{
_____
<______>
<______>______
...
...
}}}
==== 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"}
}}}