Documentation for the metrics API

• Documentation for the metrics API
• correction of the allgo url from allgo.inria to allgo18.inria

Note: We should use a substitution for the ALLGO_URL (use ALLGO_URL in the rst file and makes it replaced automatically). something like replace:: (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions). I tried unsuccessfully.

api.rst

@@ -3,7 +3,7 @@
 HTTP REST API v1
 =================
 
-In order to use the A||GO HTTP API, you have to copy your **private token** from your profile [page](https://allgo.inria.fr/users/edit)
+In order to use the A||GO HTTP API, you have to copy your **private token** from your profile `profile <https://allgo18.inria/profile>`_
 
 
 Post a job
@@ -32,7 +32,7 @@ Post a job
 
       {
         "id":40155,
-        "url":"https://allgo.inria.fr/api/v1/jobs/40155"
+        "url":"https://allgo18.inria.fr/api/v1/jobs/40155"
       }
 
 
@@ -43,7 +43,7 @@ Here is a example with curl
 
     curl -H 'Authorization: Token token=<your_private_token>' -X POST -F job[webapp_id]=<service_id>
          -F job[param]='' -F files[0]=@<path_to_file0> -F files[1]=@<path_to_file1>
-         https://allgo.inria.fr/api/v1/jobs
+         https://allgo18.inria.fr/api/v1/jobs
 
 
 This request will return you, either the errors, or if it's ok, your **job_id**
@@ -67,10 +67,10 @@ Third, check the resulting job to get the url files with :
 
     {
      "40155":
-       {"conv1_samusa.txt":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1_samusa.txt",
-        "conv1.json":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.json",
-        "conv1.mp3":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.mp3",
-        "allgo.log":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/allgo.log"
+       {"conv1_samusa.txt":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1_samusa.txt",
+        "conv1.json":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.json",
+        "conv1.mp3":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.mp3",
+        "allgo.log":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/allgo.log"
         },
      "status":"done"
      }
@@ -83,7 +83,7 @@ Each file could be downloaded with the link associated.
 ..  http:example:: curl wget httpie python-requests
 
     GET /api/v1/jobs/40155 HTTP/1.1
-    Host: allgo.inria.fr
+    Host: allgo18.inria.fr
     Accept: application/json
     Authorization: Token token=<your_private_token>
 
@@ -93,15 +93,73 @@ Each file could be downloaded with the link associated.
 
     {
      "40155":
-       {"conv1_samusa.txt":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1_samusa.txt",
-        "conv1.json":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.json",
-        "conv1.mp3":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.mp3",
-        "allgo.log":"https://allgo.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/allgo.log"
+       {"conv1_samusa.txt":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1_samusa.txt",
+        "conv1.json":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.json",
+        "conv1.mp3":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/conv1.mp3",
+        "allgo.log":"https://allgo18.inria.fr/datastore/6/1/0fe2bc68b835e9a1f681e38d5e87001ef955e345/allgo.log"
         },
      "status":"done"
      }
 
 
 
+Get metrics
+------------
+We provide a way to get simple metrics about *your* applications.
+For the moment it allows to get for a given webapp, the number of job over a period of time.
+
+.. 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_state** : the number of jobs per time period and per state 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>
+
+
+   ..  http:example:: curl wget httpie python-requests
+
+       GET /api/v1/metrics/151?from=2019-01-01&step=day HTTP/1.1
+       Host: allgo18.inria.fr
+       Accept: application/json
+       Authorization: Token token=<your_private_token>
+
 
+   **Example response**:
+
+   .. sourcecode:: http
 
+    {
+      "GATB-Compiler": {
+        "from": "01-01-2017 00:00",
+        "to": "01-01-2018 00:00",
+        "data": [
+          {
+            "time_period": "2017-01-01T00:00:00Z",
+            "user": 149,
+            "uname": "u149",
+            "n": 2499
+          },
+          {
+            "time_period": "2017-01-01T00:00:00Z",
+            "user": 35,
+            "uname": "u35",
+            "n": 22
+          },
+          ...
+        ]
+      }
+    }