2.8. API

2.8.1. Présentation

L'API (Application Programming Interface) est l'ensemble des endpoints (appelés aussi ressources ou fin d'URL).
Chacun de ces endpoints permet d'effectuer une action sur la GBox et retourner des informations et ceci sans avoir à passer par l'interface graphique GBox.
Ceci facilite le partage et l’intégration de fonctionnalités et des données de la GBox dans des architectures existantes.
Chacun de ces endpoints a une syntaxe simple.
Ces endpoints sont prédéterminées : la liste de ces endpoints est limitée et est affichée par thème (analysers...).

Note

La liste des endpoints est donnée dans le paragraphe Liste des endpoints.

L'exécution de ces endpoints peut se faire :

  • via SWAGGER (Utilisation via l'interface graphique swagger) :
    ceci permet l'utilisation des endpoints et de comprendre son paramétrage et pouvoir tester son exécution et d'analyser ses résultats

  • via CURL (Utilisation via CURL) : ceci permet d'exécuter directement une requête Curl et de ne pas passer par l'interface graphique

2.8.2. Utilisation via l'interface graphique swagger

Chaque endpoint de l'API :

  • effectue une opération précise. Son nom et sa description sont indiquées dans l'interface graphique (ou dans la liste Liste des endpoints)

  • effectue une méthode parmi les quatre possibles : GET (Obtenir), DELETE (Supprimer), POST (Publier), PUT (Modifier)

  • a besoin de droits d'authentification qui sont les mêmes que pour l'interface graphique (Operators ou Administrators)

  • peut avoir besoin de paramètres de fonctionnement (entrée et /ou sortie) : par exemple, dans le cas d'un filtre, la valeur de ce filtre doit être indiquée.

Toutes ces informations sont visibles dans l'interface graphique swagger et sont donc, la documentation de l’ensemble de nos endpoints API.
La description d'interface graphique swagger est donnée dans la Présentation de l'interface API GBOX.
Pour la mise en œuvre de l'interface swagger, voir la procédure d'Utilisation d'un endpoint API.

Cette interface permet de :

  • avoir la liste des endpoints existants (listés par thème)

  • avoir le détail des paramètres éventuels pour l'exécution d'un endpoint

  • avoir des informations sur le résultat attendu (modèle des données et un exemple avec des valeurs par défaut)

  • exécuter des requêtes

  • récupérer la commande Curl équivalente à la requête via l'API

2.8.3. Utilisation via CURL

Il est possible d’exécuter un endpoint par une commande curl.
Cette commande est accessible via l'interface graphique swagger après avoir sélectionné le endpoint, entrer les paramètres éventuels puis lancer l'exécution du endpoint.
La commande curl est affichée dans la zone `Responses`.

Note

Envoi d’une requête pour lister les moteurs de la GBox (endpoint api/analysers) :

curl -X GET "https://x.x.x.x/api/analysers/" -H  "accept: application/json" -H  "authorization: Basic dG90bzpTYW5kcmluZSwxMDA=" -H  "X-CSRFToken: PsMZMavgOibfe5giFCImu0YYTWqvB2AdhR1y"

où x.x.x.x est l'adresse IP de la Gbox.

2.8.4. Authentification et accès à l'API GBox

L’accès à l'interface graphique swagger se fait via l'interface GBox puis appui sur le bouton `API`.
L’authentification sur la GBox permet l’accès à l'API GBox (pour plus d'infos, voir le paragraphe Barre de titre).
L'utilisation de requête curl nécessite que l’authentification se fasse dans la requête.
Cette authentification se fait à l'aide des couples nom/mot de passe ou des tokens définis dans l'Ecran `Admin-GBox - Accounts` de la Web UI.