From 75f849c34e08c9855472e74cf6a6805d6332a26d Mon Sep 17 00:00:00 2001 From: Didier Date: Sat, 29 Jul 2023 18:46:41 +0200 Subject: [PATCH] add documentation --- docs/api.fr.md | 234 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/api.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 466 insertions(+) create mode 100644 docs/api.fr.md create mode 100644 docs/api.md diff --git a/docs/api.fr.md b/docs/api.fr.md new file mode 100644 index 00000000..a5ed1927 --- /dev/null +++ b/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 + "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 + "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 + "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 + "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 . + +``` + diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..ed63c7ce --- /dev/null +++ b/docs/api.md @@ -0,0 +1,232 @@ +## API + +Deming can be modified or updated via a REST API. + +A REST API ([Representational State Transfer](https://fr.wikipedia.org/wiki/Representational_state_transfer)) +is an application programming interface that respects the constraints of the REST +architecture and enables interaction with RESTful web services. + +### Installing the API + +To install the API, you need to install Passport by running this command: + +```bash +php artisan passport:install +``` + +- The Docker environment supports this functionality natively, via the entrypoint. + +### The APIs + +- /api/attributes + +- /api/domains + +- /api/measures + +- /api/controls + +- /api/documents + +### Actions managed by the resource controller + +Requests and URIs for each api are shown in the table below. + +| Request | URI | Action +|-----------|--------------------|--------------------------------| +| GET | /api/objects | returns the list of objects | +| GET /api/objets/{id} | returns object {id} | +| POST | /api/objects | save new object | +| PUT/PATCH | /api/objets/{id} | update object {id} | +| /api/objets/{id} | delete object {id} | + + +### Access rights + +To access the APIs, you need to identify yourself as a Deming application user. +This user must have the "API" role. + +When authentication is successful, the API sends a "token" which must be passed in the "Authorization" header of the API request. + +### Examples + +Here are a few examples of how to use the API with PHP: + +#### Authentication + +```php + "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 + "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); + +``` + +#### Get a control + +```php + "http://127.0.0.1:8000/api/controls/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); +``` + +#### Update a control + +```php + "http://127.0.0.1:8000/api/controls/1", + 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( +... + ), + 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 . + +``` +