Resolve "define the output of metrics API."

Closes #6

Now a user should be able to know the output of each type of metrics.

api.rst

@@ -117,23 +117,6 @@ For the moment it allows to get for a given webapp, the number of job over a per
 
 .. http:get:: /api/v1/metrics/(string: metric_type)/(int: webapp_id)
 
-   We provide 3 metrics :
-
-     - **per_user**   : the number of jobs per time period and per user.
-     - **per_result** : the number of jobs per time period and per result.
-     - **created**    : the number of jobs created per time period.
-
-
-   3 parameters can refine your request :
-
-     - **step** : string [*year,month,week,day*], the step of aggregation.
-     - **from** : date, the begin (including) of the time period to interrogate.
-     - **to**   : date, the end (excluding) of the time period to interrogate.
-
-        *Note: the dates should have the format "%Y-%m-%d", so 2019-04-01 for the first of april 2019.*
-
-   .. mettre les valeurs par défaut ?
-
    :reqheader Authorization: Token token=<your_private_token>
 
 
@@ -170,3 +153,101 @@ For the moment it allows to get for a given webapp, the number of job over a per
         ]
       }
     }
+
+   We provide 3 metrics :
+
+     - **per_user**   : the number of jobs per time period and per user.
+     - **per_result** : the number of jobs per time period and per result.
+     - **created**    : the number of jobs created per time period.
+
+
+   3 parameters can refine your request :
+
+     - **step** : string [*year,month,week,day*], the step of aggregation.
+     - **from** : date, the begin (including) of the time period to interrogate.
+     - **to**   : date, the end (excluding) of the time period to interrogate.
+
+        *Note: the dates should have the format "%Y-%m-%d", so 2019-04-01 for the first of april 2019.*
+
+   .. mettre les valeurs par défaut ?
+
+output format
+^^^^^^^^^^^^^
+It returns a dictionnary with 4 keys '*from*', '*to*' [date] remind the date range,
+'*step*' the data aggregation interval,
+and '*data*' which contains a list of dictionnaries {*time_period*:, *n*:}
+
+The format of the data value is slightly different regarding the 'what' parameter.
+
+ - created :
+
+   For each step, count the number of jobs created.
+   Each record has the following keys :
+     * "n" : the count.
+     * "time_period" : the value date = first day of year or month or the day the count happens.
+
+   .. sourcecode:: json
+
+    "data": [
+      {
+        "n": 13,
+        "time_period": "2020-02-04"
+      },
+      {
+        "n": 3,
+        "time_period": "2020-02-10"
+      },
+      {
+        "n": 1,
+        "time_period": "2020-02-17"
+      }
+    ]
+
+ - per_user :
+
+   For each username and each step, count its number of jobs.
+   Each record has the following keys :
+     * "n" : the count.
+     * "time_period" : the value date = first day of year or month or the day the count happens.
+     * "uname" : the username.
+     * "user" : the user id.
+
+   .. sourcecode:: json
+
+    "data": [
+      {
+        "n": 11,
+        "uname": "devel@localhost",
+        "time_period": "2020-02-01",
+        "user": 2
+      },
+      {
+        "n": 6,
+        "uname": "guest@localhost",
+        "time_period": "2020-02-01",
+        "user": 3
+      }
+    ]
+
+ - per_result :
+
+   For each result type and each step, count its number of jobs.
+   Each record has the following keys :
+     * "n" : the count.
+     * "time_period" : the value date = first day of year or month or the day the count happens.
+     * "result" : the result category.
+
+   .. sourcecode:: json
+
+    "data": [
+      {
+        "n": 14,
+        "time_period": "2020-02-01",
+        "result": "SUCCESS"
+      },
+      {
+        "n": 3,
+        "time_period": "2020-02-01",
+        "result": "ABORTED"
+      }
+    ]