From 7011ca0c20a6109865f5bc6869208632f5359811 Mon Sep 17 00:00:00 2001
From: Lucas Fernandes de Oliveira <lfo14@inf.ufpr.br>
Date: Mon, 18 Sep 2017 08:43:08 -0300
Subject: [PATCH] Issue #20: Add docs to gitlab pages
Signed-off-by: Lucas Fernandes de Oliveira <lfo14@inf.ufpr.br>
---
.gitignore | 1 +
.gitlab-ci.yml | 11 +++
doc/api-v1-reference.html | 170 --------------------------------------
3 files changed, 12 insertions(+), 170 deletions(-)
delete mode 100644 doc/api-v1-reference.html
diff --git a/.gitignore b/.gitignore
index 832572ed..a4a4caef 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,3 +16,4 @@
/build
/dist
/database/views
+/doc
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 893848c6..cf7c7f8e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -22,3 +22,14 @@ run_tests:
tags:
- node
- postgres
+
+pages:
+ script:
+ - mkdir -p doc
+ - npm run doc-api
+ - mv doc public
+ artifacts:
+ paths:
+ - public
+ only:
+ - issue/20
diff --git a/doc/api-v1-reference.html b/doc/api-v1-reference.html
deleted file mode 100644
index 4e7f81d0..00000000
--- a/doc/api-v1-reference.html
+++ /dev/null
@@ -1,170 +0,0 @@
-<!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">×</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">×</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">×</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'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 'met:electricCharge' 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">×</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>
\ No newline at end of file
--
GitLab