Changes between Initial Version and Version 1 of GENIMonitoring/API


Ignore:
Timestamp:
02/22/16 14:14:38 (8 years ago)
Author:
Caylin Hickey
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • GENIMonitoring/API

    v1 v1  
     1[[PageOutline]]
     2
     3''Note: this is a draft page documenting the development of the GENI Collector API access.''
     4
     5= GENI Collector API =
     6
     7This page details the developmental progress and description of the GENI Collector API access system.
     8
     9The API is accessed in similar fashion to accessing metric data from a GENI Monitoring DataStore. (ie: /API/data/?q={json})
     10
     11== Examples ==
     12
     13=== Request ===
     14
     15==== Data Request JSON ====
     16
     17{{{
     18  {
     19    eventType: [
     20      "opsmonitoring:_____",
     21      ...
     22    ],
     23    ts: {
     24      gte*: #####,        // milliseconds or microseconds
     25      lt*: #####          // milliseconds or microseconds
     26    },
     27    obj: {
     28      type*: _______,     // string of pollable object time (aggregate, node, interface, etc.)
     29      id: [
     30        _______,         // string of either urn or id of a requested target
     31        ...
     32      ]
     33    },
     34    output: _______      // string of output format type (xml or json). if not supplied, defaults to xml
     35  }
     36}}}
     37
     38''Note: items denoted with a (*) are required''
     39
     40==== Example Data Request URL ====
     41
     42{{{
     43http://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}
     44}}}
     45
     46=== Response ===
     47
     48==== Data Response (XML) [Default] ====
     49
     50{{{
     51<?xml version="1.0" encoding="UTF-8"?>
     52<response>
     53  <request>
     54    <url>_____</url>                                                    // the url from which this response was generated
     55  </request>
     56  <objects>
     57    <object urn="_____" id="_____" schema="_____" objectType="_____">   // descriptors of this object   
     58      <events eventType="_____" units="_____">                          // descriptors of this eventType list
     59        <event>
     60          <ts>#####</ts>                                                // timestamp of this event (in milliseconds)
     61          <v>_____</v>                                                  // value for this eventType at this timestamp
     62        </event>
     63        ...
     64      </events>
     65    </object>
     66    ...
     67  </objects>
     68</response>
     69}}}
     70
     71==== Data Response (JSON) ====
     72
     73{{{
     74  [
     75    {
     76      "$schema": "http://www.gpolab.bbn.com/monitoring/schema/20151105/data#",
     77      "description": "ops_monitoring:_____ for _____ of type _____",             // eventType, id, objectType
     78      "eventType": "ops_monitoring:_____",                                       // eventType
     79      "id": "_____:_____",                                                       // eventType, id
     80      "subject": {
     81        "href": "_____#"                                                         // schema of objectType
     82      },
     83      "tsdata": [
     84        "ts": #####,                                                             // (in milliseconds)
     85        "v": _____                                                               // depends on the eventType
     86      ],
     87      "units": _____                                                             // describes the units fo the eventType
     88    }
     89  ]
     90}}}
     91
     92== Reference ==
     93
     94=== Schema ===
     95
     96==== Request JSON ====
     97
     98{{{
     99{
     100  "$schema": "http://json-schema.org/draft-03/schema#",
     101  "additionalProperties": false,
     102  "description": "Request Object for GENI Monitoring Collector API.",
     103  "id": "localhost:9000/schema/request#",
     104  "name": "request",
     105  "properties": {
     106    "$schema": {
     107      "default": "localhost:9000/schema/request#",
     108      "description": "The schema of this file.",
     109      "format": "uri",
     110      "required": false,
     111      "type": "string"
     112    },
     113    "eventType": {
     114      "additionalProperties": false,
     115      "description": "Event types to search for. If this is missing, all of the requested events for target type are returned.",
     116      "items": {
     117        "description": "An array holding the GENI IDs of the request targets or a single element 'all'.",
     118        "required": true,
     119        "type": "string"
     120      },
     121      "required": false,
     122      "type": "array"
     123    },
     124    "obj": {
     125      "description": "Targets for this request.",
     126      "properties": {
     127        "id": {
     128          "description": "Array holding the GENI urns of the targets of the request.",
     129          "required": false,
     130          "type": "array"
     131        },
     132        "type": {
     133          "description": "The type of objects being requested.",
     134          "required": true,
     135          "type": "string"
     136        }
     137      },
     138      "required": true,
     139      "type": "object"
     140    },
     141    "output": {
     142      "description": "Output style requested. Defaults to XML if not specified.",
     143      "enum": [
     144        "json",
     145        "xml"
     146      ],
     147      "required": false
     148    },
     149    "ts": {
     150    "description": "Timestamps for request",
     151    "properties": {
     152        "gte": {
     153          "description": "Timestamp for DATA requests indicating the start of the time range in either milliseconds or microseconds. Required for DATA requests.",
     154          "required": true,
     155          "type": "number"
     156        },
     157        "lt": {
     158          "description": "Timestamp for DATA requests indicating the end of the time range in either milliseconds or microseconds. Required for DATA requests.",
     159          "required": true,
     160          "type": "number"
     161        },
     162        "ts": {
     163          "description": "Timestamp for INFO requests in either milliseconds or microseconds. If missing, defaults to current time.",
     164          "required": false,
     165          "type": "number"
     166        }
     167      },
     168      "required": true,
     169      "type": "object"
     170    }
     171  },
     172  "type": "object"
     173}
     174}}}