Merge branch 'add_basic_queries' into 'development'

Implement basic queries for enrollments

# Description

Implemented enrollments queries per:
- Region
- State
- City

The *census_year* parameter is *mandatory* and should be included in all requests.

The "/enrollments" route supports the following parameters

- aggregate: metric to aggregate, can be {state, region, city}. When no parameter is supplied or the parameter is not supported, the API assumes the whole country.
- id: record identifer of the metric to aggregate (e.g. one specific state or region), it only applies when the aggregate parameters is passed and is valid. Again, when no parameter is specified, the API assumes the whole range of values the metric can take (e.g. all states or all regions).
- adm_dependency_id: administrative dependency identifier, the possible values are shown in the Table 1.

- location_id: location identifier, its possible values are given in Table 2.

# Tables

*Table 1:* Administrative dependency table.

| adm_dependency_id | name           |
|---------------------------|---------------|
| 0                                          | All records  |
| 1                                          | Federal        |
| 2                                          | Estadual     |
| 3                                          | Municipal   |
| 4                                           | Privada       |

*Table 2:* Location table.

| location_id  | name            |
|----------------|---------------|
| 0                        | All records  |
| 1                        | Urbana        |
| 2                        | Rural            |

# Response Format

The API returns a JSON array with name "result" where every array has following attributes:
- name: Name of the metric (e.g. name of a state, city or region)
- total: Total number of enrollments for the selected metric and given parameters.

# Examples
Retrieve the number of enrollments of 2014 for the whole country:
> /api/v1/enrollments?census_year=2014

Retrieve the number of enrollments of 2013 for a given region:
> /api/v1/enrollments?census_year=2013&aggregate=region&id=1

Retrieve the number of enrollments of 2012 for all rural locations in the state of Paraná:
> /api/v1/enrollments?census_year=2012&aggregate=state&id=41&location_id=2

Retrieve the number of enrollments of 2012 for the North region:
> /api/v1/enrollments?census_year=2012&aggregate=region&id=1

See merge request !5

libs/routes/api.js

@@ -23,22 +23,36 @@ router.get('/', function (req, res) {
 router.get('/year_range', function(req, res) {
     var yearSql = "SELECT MIN(t.ano_censo) AS start_year, MAX(t.ano_censo) AS end_year FROM turmas AS t";
     conn.query(yearSql, true).then(function(result) {
+      if (req.query.format === 'csv') {
+        res.csv(result.data);
+      } else if (req.query.format === 'xml') {
+        res.send(xml("result", JSON.stringify({year_range: result.data})))
+      }
+      else {
         res.json({
             result: result.data
-        })
+        });
+      }
     });
 })
 
 router.get('/data', function(req, res) {
-    console.log(req.query)
-    console.log(req.query.met)
-    console.log(req.query.dim)
+    log.debug(req.query)
+    log.debug(req.query.met)
+    log.debug(req.query.dim)
     conn.query(
         'SELECT * FROM turmas'
     ).then(function(result) {
+      if (req.query.format === 'csv') {
+        res.csv(result.data);
+      } else if (req.query.format === 'xml') {
+        res.send(xml("result", JSON.stringify({data: result.data})))
+      }
+      else {
         res.json({
-            result: result
-        })
+            result: result.data
+        });
+      }
     })
 })
 
@@ -47,8 +61,7 @@ router.get('/enrollments', function(req, res) {
     var id = 0;
     var location_id = 0;
     var adm_dependency_id = 0;
-    var start_year = 0;
-    var end_year = 0;
+    var census_year = 0;
     var enrollmentSql = "";
 
     if (params.id)
@@ -63,77 +76,62 @@ router.get('/enrollments', function(req, res) {
 
     if (params.adm_dependency_id)
     {
-        adm_dependency_id = parseInt(params.adm_dependency_id)
-    }
-
-    if (!params.start_year && !params.end_year)
-    {
-        var yearSql = "SELECT MIN(t.ano_censo) AS start_year, MAX(t.ano_censo) AS end_year FROM turmas AS t";
-        conn.query(yearSql, true).then(function(result) {
-            start_year = result.data.start_year;
-            end_year = result.data.end_year;
-        });
-    }
-
-    if (params.start_year)
-    {
-        start_year = parseInt(params.start_year, 10);
-    } else if (start_year == 0) {  // if start_year was not previously set
-        var yearSql = "SELECT MIN(t.ano_censo) AS start_year FROM turmas AS t";
-        conn.query(yearSql, true).then(function(result) {
-            start_year = result.data.start_year;
-        });
+        adm_dependency_id = parseInt(params.adm_dependency_id, 10);
     }
 
-    if (params.end_year)
+    if (params.census_year)
     {
-        end_year = parseInt(params.end_year, 10);
-    } else if (end_year == 0) {  // if end_year was not previously set
-        var yearSql = "SELECT MAX(t.ano_censo) AS end_year FROM turmas AS t";
-        conn.query(yearSql, true).then(function(result) {
-            end_year = result.data.end_year;
-        });
+        census_year = parseInt(params.census_year, 10);
     }
 
+    /**
+     * FIXME: parameter substitution in the queries is not safe (vulnerable to
+     * SQL injection). Substitution from MonetDB module is not working for some
+     * reason.
+     */
     switch(params.aggregate)
     {
-    /** TODO: function to compute enrollments by state in the database not yet available
+    case "city":
+        if (id) {
+            enrollmentSql = "SELECT nome AS name, total FROM mat_municipio(" + id + "," + census_year + "," + adm_dependency_id + "," + location_id + ")";
+        } else {
+            enrollmentSql = "SELECT nome AS name, total FROM mat_municipios(" + census_year + "," + adm_dependency_id + "," + location_id + ")";
+        }
+        break;
     case "state":
-        tbl_name = "matriculas_estado";
+        if (id) {
+            enrollmentSql = "SELECT nome AS name, total FROM mat_estado(" + id + "," + census_year + "," + adm_dependency_id + "," + location_id + ")";
+        } else {
+            enrollmentSql = "SELECT nome AS name, total FROM mat_estados(" + census_year + "," + adm_dependency_id + "," + location_id + ")";
+        }
         break;
-    */
     case "region":
-        if (!id) {
-            enrollmentSql = "SELECT nome AS name, total, ano_inicio AS start_year, ano_fim AS end_year \
-                FROM matRegioes(" + start_year + "," + end_year + "," + adm_dependency_id + "," + location_id + ")";
+        if (id) {
+            enrollmentSql = "SELECT nome AS name, total FROM mat_regiao(" + id + "," + census_year + "," + adm_dependency_id + "," + location_id + ")";
         } else {
-            enrollmentSql = "SELECT nome AS name, total, ano_inicio AS start_year, ano_fim AS end_year \
-                FROM matRegiao(" + id + "," + start_year + "," + end_year + "," + adm_dependency_id + "," + location_id + ")";
+            enrollmentSql = "SELECT nome AS name, total FROM mat_regioes(" + census_year + "," + adm_dependency_id + "," + location_id + ")";
         }
         break;
     default:
-        enrollmentSql = "SELECT nome AS name, total, ano_inicio AS start_year, ano_fim AS end_year \
-            FROM matBrasil(" + start_year + "," + end_year + "," + adm_dependency_id + "," + location_id + ")";
+        enrollmentSql = "SELECT nome AS name, total FROM mat_brasil(" + census_year + "," + adm_dependency_id + "," + location_id + ")";
     }
 
     log.debug(params);
-    log.debug("Executing query :\"" + enrollmentSql + "\"");
+    log.debug("Executing query: " + enrollmentSql);
 
     conn.query(enrollmentSql, true).then(function(result) {
         log.debug(result);
         if (req.query.format === 'csv') {
-          res.csv(result.data)
+          res.csv(result.data);
         } else if (req.query.format === 'xml') {
-          res.set('Content-Type', 'text/xml')
-          res.send(xml({
-            result: result.data
-          }))
+          res.send(xml("result", JSON.stringify({enrollments: result.data})))
         }
         else {
           res.json({
               result: result.data
-          })
+          });
         }
+        log.debug("All resources were released");
     });
 })