api-v1-reference.html 18.5 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
<!DOCTYPE HTML><html><head><title>BlenDB API API documentation</title><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><meta name="generator" content="https://github.com/raml2html/raml2html 3.0.0"><link rel="stylesheet" href="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/styles/default.min.css"><script type="text/javascript" src="https://code.jquery.com/jquery-1.11.0.min.js"></script><script type="text/javascript" src="https://netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script><script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.3.0/highlight.min.js"></script><script type="text/javascript">
      $(document).ready(function() {
        $('.page-header pre code, .top-resource-description pre code, .modal-body pre code').each(function(i, block) {
          hljs.highlightBlock(block);
        });

        $('[data-toggle]').click(function() {
          var selector = $(this).data('target') + ' pre code';
          $(selector).each(function(i, block) {
            hljs.highlightBlock(block);
          });
        });

        // open modal on hashes like #_action_get
        $(window).bind('hashchange', function(e) {
          var anchor_id = document.location.hash.substr(1); //strip #
          var element = $('#' + anchor_id);

          // do we have such element + is it a modal?  --> show it
          if (element.length && element.hasClass('modal')) {
            element.modal('show');
          }
        });

        // execute hashchange on first page load
        $(window).trigger('hashchange');

        // remove url fragment on modal hide
        $('.modal').on('hidden.bs.modal', function() {
          try {
            if (history && history.replaceState) {
                history.replaceState({}, '', '#');
            }
          } catch(e) {}
        });
      });
    </script><style>
      .hljs {
        background: transparent;
      }
      .parent {
        color: #999;
      }
      .list-group-item > .badge {
        float: none;
        margin-right: 6px;
      }
      .panel-title > .methods {
        float: right;
      }
      .badge {
        border-radius: 0;
        text-transform: uppercase;
        width: 70px;
        font-weight: normal;
        color: #f3f3f6;
        line-height: normal;
      }
      .badge_get {
        background-color: #63a8e2;
      }
      .badge_post {
        background-color: #6cbd7d;
      }
      .badge_put {
        background-color: #22bac4;
      }
      .badge_delete {
        background-color: #d26460;
      }
      .badge_patch {
        background-color: #ccc444;
      }
      .list-group, .panel-group {
        margin-bottom: 0;
      }
      .panel-group .panel+.panel-white {
        margin-top: 0;
      }
      .panel-group .panel-white {
        border-bottom: 1px solid #F5F5F5;
        border-radius: 0;
      }
      .panel-white:last-child {
        border-bottom-color: white;
        -webkit-box-shadow: none;
        box-shadow: none;
      }
      .panel-white .panel-heading {
        background: white;
      }
      .tab-pane ul {
        padding-left: 2em;
      }
      .tab-pane h1 {
        font-size: 1.3em;
      }
      .tab-pane h2 {
        font-size: 1.2em;
        padding-bottom: 4px;
        border-bottom: 1px solid #ddd;
      }
      .tab-pane h3 {
        font-size: 1.1em;
      }
      .tab-content {
        border-left: 1px solid #ddd;
        border-right: 1px solid #ddd;
        border-bottom: 1px solid #ddd;
        padding: 10px;
      }
      #sidebar {
        margin-top: 30px;
        padding-right: 5px;
        overflow: auto;
        height: 90%;
      }
      .top-resource-description {
        border-bottom: 1px solid #ddd;
        background: #fcfcfc;
        padding: 15px 15px 0 15px;
        margin: -15px -15px 10px -15px;
      }
      .resource-description {
        border-bottom: 1px solid #fcfcfc;
        background: #fcfcfc;
        padding: 15px 15px 0 15px;
        margin: -15px -15px 10px -15px;
      }
      .resource-description p:last-child {
        margin: 0;
      }
      .list-group .badge {
        float: left;
      }
      .method_description {
        margin-left: 85px;
      }
      .method_description p:last-child {
        margin: 0;
      }
      .list-group-item {
        cursor: pointer;
      }
      .list-group-item:hover {
        background-color: #f5f5f5;
      }

      pre code {
        overflow: auto;
        word-wrap: normal;
        white-space: pre;
      }
    </style></head><body data-spy="scroll" data-target="#sidebar"><div class="container"><div class="row"><div class="col-md-9" role="main"><div class="page-header"><h1>BlenDB API API documentation <small>version v1</small></h1><p>http://blendb.c3sl.ufpr.br/api/v1</p></div><div class="panel panel-default"><div class="panel-heading"><h3 id="metrics" class="panel-title">/metrics</h3></div><div class="panel-body"><div class="top-resource-description"><p>A Metric represents a statistic that can be queried to generate reports. This collection allows the user to list all the metrics available in the system and their descriptions.</p></div><div class="panel-group"><div class="panel panel-white"><div class="panel-heading"><h4 class="panel-title"><a class="collapsed" data-toggle="collapse" href="#panel_metrics"><span class="parent"></span>/metrics</a> <span class="methods"><a href="#metrics_get"><span class="badge badge_get">get <span class="glyphicon glyphicon-lock" title="Authentication required"></span></span></a></span></h4></div><div id="panel_metrics" class="panel-collapse collapse"><div class="panel-body"><div class="list-group"><div onclick="window.location.href = '#metrics_get'" class="list-group-item"><span class="badge badge_get">get <span class="glyphicon glyphicon-lock" title="Authentication required"></span></span><div class="method_description"></div><div class="clearfix"></div></div></div></div></div><div class="modal fade" tabindex="0" id="metrics_get"><div class="modal-dialog"><div class="modal-content"><div class="modal-header"><button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button><h4 class="modal-title" id="myModalLabel"><span class="badge badge_get">get <span class="glyphicon glyphicon-lock" title="Authentication required"></span></span> <span class="parent"></span>/metrics</h4></div><div class="modal-body"><div class="alert alert-warning"><span class="glyphicon glyphicon-lock" title="Authentication required"></span> Secured by <b>oauth_2_0</b><p>OAuth2 is a protocol that lets apps request authorization to private details in the system while avoiding the use of passwords. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.</p></div><ul class="nav nav-tabs"><li><a href="#metrics_get_securedby" data-toggle="tab">Security</a></li></ul><div class="tab-content"><div class="tab-pane" id="metrics_get_securedby"><h1>Secured by</h1><h1>Secured by oauth_2_0</h1><h3>Headers</h3><ul><li><strong>Authorization</strong>: <em>(string)</em><p>Used to send a valid OAuth 2 access token. Do not use together with the "access_token" query string parameter.</p></li></ul><h2>HTTP status code <a href="http://httpstatus.es/401" target="_blank">401</a></h2><p>Bad or expired token. This can happen if access token has expired or has been revoked by the user.</p><h2>HTTP status code <a href="http://httpstatus.es/403" target="_blank">403</a></h2><p>Bad OAuth2 request (wrong consumer key, bad nonce, expired timestamp, ...).</p></div></div></div></div></div></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h3 id="dimensions" class="panel-title">/dimensions</h3></div><div class="panel-body"><div class="top-resource-description"><p>A Dimension allows the data to be aggregated by one or more columns. This collection allows the user to list all the dimensions available in the system and their descriptions.</p></div><div class="panel-group"><div class="panel panel-white"><div class="panel-heading"><h4 class="panel-title"><a class="collapsed" data-toggle="collapse" href="#panel_dimensions"><span class="parent"></span>/dimensions</a> <span class="methods"><a href="#dimensions_get"><span class="badge badge_get">get <span class="glyphicon glyphicon-lock" title="Authentication required"></span></span></a></span></h4></div><div id="panel_dimensions" class="panel-collapse collapse"><div class="panel-body"><div class="list-group"><div onclick="window.location.href = '#dimensions_get'" class="list-group-item"><span class="badge badge_get">get <span class="glyphicon glyphicon-lock" title="Authentication required"></span></span><div class="method_description"></div><div class="clearfix"></div></div></div></div></div><div class="modal fade" tabindex="0" id="dimensions_get"><div class="modal-dialog"><div class="modal-content"><div class="modal-header"><button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button><h4 class="modal-title" id="myModalLabel"><span class="badge badge_get">get <span class="glyphicon glyphicon-lock" title="Authentication required"></span></span> <span class="parent"></span>/dimensions</h4></div><div class="modal-body"><div class="alert alert-warning"><span class="glyphicon glyphicon-lock" title="Authentication required"></span> Secured by <b>oauth_2_0</b><p>OAuth2 is a protocol that lets apps request authorization to private details in the system while avoiding the use of passwords. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.</p></div><ul class="nav nav-tabs"><li><a href="#dimensions_get_securedby" data-toggle="tab">Security</a></li></ul><div class="tab-content"><div class="tab-pane" id="dimensions_get_securedby"><h1>Secured by</h1><h1>Secured by oauth_2_0</h1><h3>Headers</h3><ul><li><strong>Authorization</strong>: <em>(string)</em><p>Used to send a valid OAuth 2 access token. Do not use together with the "access_token" query string parameter.</p></li></ul><h2>HTTP status code <a href="http://httpstatus.es/401" target="_blank">401</a></h2><p>Bad or expired token. This can happen if access token has expired or has been revoked by the user.</p><h2>HTTP status code <a href="http://httpstatus.es/403" target="_blank">403</a></h2><p>Bad OAuth2 request (wrong consumer key, bad nonce, expired timestamp, ...).</p></div></div></div></div></div></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h3 id="data" class="panel-title">/data</h3></div><div class="panel-body"><div class="top-resource-description"><p>This is the main part of the API. You may query it for report data by specifying metrics (at least one). You may also supply additional query parameters such as dimensions, filters, and start/end dates to refine your query.</p></div><div class="panel-group"><div class="panel panel-white"><div class="panel-heading"><h4 class="panel-title"><a class="collapsed" data-toggle="collapse" href="#panel_data"><span class="parent"></span>/data</a> <span class="methods"><a href="#data_get"><span class="badge badge_get">get</span></a></span></h4></div><div id="panel_data" class="panel-collapse collapse"><div class="panel-body"><div class="list-group"><div onclick="window.location.href = '#data_get'" class="list-group-item"><span class="badge badge_get">get</span><div class="method_description"></div><div class="clearfix"></div></div></div></div></div><div class="modal fade" tabindex="0" id="data_get"><div class="modal-dialog"><div class="modal-content"><div class="modal-header"><button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button><h4 class="modal-title" id="myModalLabel"><span class="badge badge_get">get</span> <span class="parent"></span>/data</h4></div><div class="modal-body"><ul class="nav nav-tabs"><li class="active"><a href="#data_get_request" data-toggle="tab">Request</a></li><li><a href="#data_get_response" data-toggle="tab">Response</a></li></ul><div class="tab-content"><div class="tab-pane active" id="data_get_request"><h3>Query Parameters</h3><ul><li><strong>filters</strong>: <em>(string)</em><p>Filters that restrict the data returned for your request.</p><p><strong>Example</strong>:</p><pre>dim:location(4).id%3D%3D10723</pre></li><li><strong>metrics</strong>: <em>required (string)</em><p>A list of comma-separated metrics.</p><p><strong>Example</strong>:</p><pre>met:daysSinceLastContact,met:estimatedNetworkBandwidth</pre></li><li><strong>dimensions</strong>: <em>required (string)</em><p>A list of comma-separated dimensions.</p><p><strong>Example</strong>:</p><pre>dim:project,dim:point</pre></li><li><strong>start-date</strong>: <em>(string - pattern: [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo))</em><p>Start date for fetching data. Requests can specify a start date formatted as YYYY-MM-DD, or as a relative date (e.g., today, yesterday, or NdaysAgo where N is a positive integer).</p><p><strong>Example</strong>:</p><pre>7daysAgo</pre></li><li><strong>end-date</strong>: <em>(string - pattern: [0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo))</em><p>End date for fetching data. Requests can specify a end date formatted as YYYY-MM-DD, or as a relative date (e.g., today, yesterday, or NdaysAgo where N is a positive integer).</p><p><strong>Example</strong>:</p><pre>yesterday</pre></li><li><strong>sort</strong>: <em>(string)</em><p>A list of comma-separated dimensions and metrics indicating the sorting order and sorting direction for the returned data.</p><p><strong>Example</strong>:</p><pre>dim:project</pre></li></ul></div><div class="tab-pane" id="data_get_response"><h2>HTTP status code <a href="http://httpstatus.es/200" target="_blank">200</a></h2><p>Query successfully executed. Data is returned in a table format.</p><h3>Body</h3><p><strong>Type: application/json</strong></p><h2>HTTP status code <a href="http://httpstatus.es/400" target="_blank">400</a></h2><p>The supplied query is invalid. Specified metric or dimension doesn&#39;t exist, incorrect formatting for a filter, unacceptable date range, etc.</p><h3>Body</h3><p><strong>Type: application/json</strong></p><p><strong>Example</strong>:</p><pre><code>{
    "id": "metric_not_found",
    "message": "The specified metric &#39;met:electricCharge&#39; could not be found."
}
</code></pre><h2>HTTP status code <a href="http://httpstatus.es/403" target="_blank">403</a></h2><p>API rate limit exceeded.</p><h3>Headers</h3><ul><li><strong>X-RateLimit-Limit</strong>: <em>(integer)</em></li><li><strong>X-RateLimit-Remaining</strong>: <em>(integer)</em></li><li><strong>X-RateLimit-Reset</strong>: <em>(integer)</em></li></ul><h3>Body</h3><p><strong>Type: application/json</strong></p><p><strong>Example</strong>:</p><pre><code>{
    id: "too_many_requests",
    message: "API Rate limit exceeded."
}
</code></pre></div></div></div></div></div></div></div></div></div></div><div class="panel panel-default"><div class="panel-heading"><h3 id="collect__sourceName_" class="panel-title">/collect/{sourceName}</h3></div><div class="panel-body"><div class="top-resource-description"><p>This API may be used to send data to the monitoring system. All data sent must be identified with a sourceName, i.e. "gesacNetworkBandwidth".</p></div><div class="panel-group"><div class="panel panel-white"><div class="panel-heading"><h4 class="panel-title"><a class="collapsed" data-toggle="collapse" href="#panel_collect__sourceName_"><span class="parent"></span>/collect/{sourceName}</a> <span class="methods"><a href="#collect__sourceName__post"><span class="badge badge_post">post</span></a></span></h4></div><div id="panel_collect__sourceName_" class="panel-collapse collapse"><div class="panel-body"><div class="list-group"><div onclick="window.location.href = '#collect__sourceName__post'" class="list-group-item"><span class="badge badge_post">post</span><div class="method_description"></div><div class="clearfix"></div></div></div></div></div><div class="modal fade" tabindex="0" id="collect__sourceName__post"><div class="modal-dialog"><div class="modal-content"><div class="modal-header"><button type="button" class="close" data-dismiss="modal" aria-hidden="true">&times;</button><h4 class="modal-title" id="myModalLabel"><span class="badge badge_post">post</span> <span class="parent"></span>/collect/{sourceName}</h4></div><div class="modal-body"><ul class="nav nav-tabs"><li class="active"><a href="#collect__sourceName__post_request" data-toggle="tab">Request</a></li><li><a href="#collect__sourceName__post_response" data-toggle="tab">Response</a></li></ul><div class="tab-content"><div class="tab-pane active" id="collect__sourceName__post_request"><h3>URI Parameters</h3><ul><li><strong>sourceName</strong>: <em>required (string - minLength: 4 - maxLength: 64 - pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$)</em><p>An identifying name for the data that is being collected.</p></li></ul><h3>Body</h3><p><strong>Type: application/json</strong></p></div><div class="tab-pane" id="collect__sourceName__post_response"><h2>HTTP status code <a href="http://httpstatus.es/200" target="_blank">200</a></h2><p>Data has been successfully received and stored by the server.</p><h2>HTTP status code <a href="http://httpstatus.es/400" target="_blank">400</a></h2><p>An error has been found in your request. You may review your request and the data that is being sent and try again later.</p><h3>Body</h3><p><strong>Type: application/json</strong></p><p><strong>Example</strong>:</p><pre><code>{
    "id": "type_error",
    "message": "Invalid type for attribute \"memory\"."
}
</code></pre><h2>HTTP status code <a href="http://httpstatus.es/403" target="_blank">403</a></h2><p>API rate limit exceeded.</p><h3>Headers</h3><ul><li><strong>X-RateLimit-Limit</strong>: <em>(integer)</em></li><li><strong>X-RateLimit-Remaining</strong>: <em>(integer)</em></li><li><strong>X-RateLimit-Reset</strong>: <em>(integer)</em></li></ul><h3>Body</h3><p><strong>Type: application/json</strong></p><p><strong>Example</strong>:</p><pre><code>{
    id: "too_many_requests",
    message: "API Rate limit exceeded."
}
</code></pre></div></div></div></div></div></div></div></div></div></div></div><div class="col-md-3"><div id="sidebar" class="hidden-print affix" role="complementary"><ul class="nav nav-pills nav-stacked"><li><a href="#metrics">/metrics</a></li><li><a href="#dimensions">/dimensions</a></li><li><a href="#data">/data</a></li><li><a href="#collect__sourceName_">/collect/{sourceName}</a></li></ul></div></div></div></div></body></html>