add documentation

docs/api.fr.md

@@ -0,0 +1,234 @@
+## API
+
+Deming peut être modifiée ou mis à jour via une REST API.
+
+Une API REST ([Representational State Transfer](https://fr.wikipedia.org/wiki/Representational_state_transfer)) 
+est une interface de programmation d'application qui respecte les contraintes du style d'architecture REST 
+et permet d'interagir avec les services web RESTful. 
+
+### Installer l'API 
+
+pour installer l'API, il est nécessaire d'installer Passport en lançant cette commande :
+
+```bash
+php artisan passport:install
+```
+
+- l'environnement Docker prend en charge cette fonctionnalité nativement, via le l'entrypoint.
+
+### Les APIs
+
+- /api/attributes
+
+- /api/domains
+
+- /api/measures
+
+- /api/controls
+
+- /api/documents
+
+### Actions gérées par le contrôleur de ressources
+
+Les requêtes et URI de chaque api est représentée dans le tableau ci-dessous.
+
+| Requête   | URI                | Action 	
+|-----------|--------------------|--------------------------------|      
+| GET       | /api/objets        | renvoie la liste des objets    |
+| GET       | /api/objets/{id}   | renvoie l'objet {id}           |
+| POST 	    | /api/objets 	     | sauve un nouvel objet          |
+| PUT/PATCH | /api/objets/{id}   | met à jour l'objet {id}        |
+| DELETE 	| /api/objets/{id}   | supprimer l'objet {id}         |
+
+
+### Droits d'accès
+
+Il faut s'identifier avec un utilisateur de l'application Deming pour pouvoir accèder aux API.
+Cet utilisateur doit disposer du rôle "API". 
+
+Lorsque l'authentification réussi, l'API envoie un "token" qui doit être passé dans l'entête "Authorization" de la requête de l'API.
+
+### Exemples
+
+Voici quelques exemples d'utilisation de l'API avec PHP :
+
+#### Authentification
+
+```php
+<?php
+    $curl = curl_init();
+
+    curl_setopt_array($curl, array(
+        CURLOPT_URL => "http://127.0.0.1:8000/api/login",
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_MAXREDIRS => 10,
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+        CURLOPT_CUSTOMREQUEST => "POST",
+        CURLOPT_POSTFIELDS => http_build_query(
+            array("email" => "api@admin.com",
+                  "password" => "12345678")),
+        CURLOPT_HTTPHEADER => array(
+            "accept: application/json",
+            "content-type: application/x-www-form-urlencoded",
+        ),
+    ));
+
+    $response = curl_exec($curl);
+    $err = curl_error($curl);
+    $info = curl_getinfo($curl);
+
+    curl_close($curl);
+
+    if ($err) {
+        set_error_handler($err);
+    } else {
+        if ($info['http_code'] == 200) {
+            $token = json_decode($response)->token;
+
+        } else {
+            set_error_handler("Login to api faild status 403");
+            error_log($responseInfo['http_code']);
+            error_log("No login api status 403");
+        }
+    }
+
+    var_dump($response);
+```
+
+#### Liste des domaines
+
+```php
+<?php
+    $curl = curl_init();
+
+    curl_setopt_array($curl, array(
+        CURLOPT_URL => "http://127.0.0.1:8000/api/domains",
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_MAXREDIRS => 10,
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+        CURLOPT_CUSTOMREQUEST => "GET",
+        CURLOPT_POSTFIELDS => null, // here you can send parameters
+        CURLOPT_HTTPHEADER => array(
+            "accept: application/json",
+            "Authorization: " . "Bearer" . " " . $token . "",
+            "cache-control: no-cache",
+            "content-type: application/json",
+        ),
+    ));
+
+
+    $response = curl_exec($curl);
+    $err = curl_error($curl);
+    curl_close($curl);
+
+    var_dump($response);
+
+```
+
+#### Récupérer un domaine
+
+```php
+<?php
+    $curl = curl_init();
+
+    curl_setopt_array($curl, array(
+        CURLOPT_URL => "http://127.0.0.1:8000/api/domains/1",
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_MAXREDIRS => 10,
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+        CURLOPT_CUSTOMREQUEST => "GET",
+        CURLOPT_POSTFIELDS => null, // here you can send parameters
+        CURLOPT_HTTPHEADER => array(
+            "accept: application/json",
+            "Authorization: " . "Bearer" . " " . $token . "",
+            "cache-control: no-cache",
+            "content-type: application/json",
+        ),
+    ));
+
+    $response = curl_exec($curl);
+    $err = curl_error($curl);
+    curl_close($curl);
+
+    var_dump($response);
+```
+
+#### Mettre à jour un domaine
+
+```php
+<?php
+   $curl = curl_init();
+
+    curl_setopt_array($curl, array(
+        CURLOPT_URL => "http://127.0.0.1:8000/api/domains/8",
+        CURLOPT_RETURNTRANSFER => true,
+        CURLOPT_MAXREDIRS => 10,
+        CURLOPT_TIMEOUT => 30,
+        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
+        CURLOPT_POST => true,
+        CURLOPT_CUSTOMREQUEST => "PUT",
+        CURLOPT_POSTFIELDS => http_build_query(
+            array(
+                'title' => 'Nouveau titre',
+                'description' => 'Nouvelle description'
+                )
+            ),
+        CURLOPT_HTTPHEADER => array(
+            "accept: application/json",
+            "Authorization: " . "Bearer" . " " . $token . "",
+            "cache-control: no-cache",
+        ),
+    ));
+
+    $response = curl_exec($curl);
+    $err = curl_error($curl);
+    curl_close($curl);
+
+    var_dump($response);
+```
+
+### Python
+
+Voici un exemple d'utilisation de l'API en Python
+
+```python
+#!/usr/bin/python3
+
+import requests
+
+vheaders = {}
+vheaders['accept'] = 'application/json'
+
+print("Login")
+response = requests.post("http://127.0.0.1:8000/api/login", 
+    headers=vheaders, 
+    data= {'email':'api@admin.localhost', 'password':'12345678'} )
+print(response.status_code)
+
+vheaders['Authorization'] = "Bearer " + response.json()['token']
+
+print("Get domains")
+response = requests.get("http://127.0.0.1:8000/api/domains", headers=vheaders)
+print(response.status_code)
+print(response.json())
+
+```
+
+### bash
+
+Voici un exemple d'utilisation de l'API en ligne de commande avec [CURL](https://curl.se/docs/manpage.html) et [JQ](https://stedolan.github.io/jq/)
+```
+# valid login and password
+data='{"email":"api@admin.localhost","password":"12345678"}'
+
+# get a token after correct login
+token=$(curl -s -d ${data} -H "Content-Type: application/json" http://localhost:8000/api/login | jq -r .token)
+
+# query users and decode JSON data with JQ.
+curl -s -H "Content-Type: application/json" -H "Authorization: Bearer ${token}" "http://127.0.0.1:8000/api/domains" | jq .
+
+```
+