5.4.1. Présentation de l'interface API GBOX

L'interface API permet :
  • d'afficher la liste par thème des endpoints existants

  • de pouvoir filtrer cette liste

  • de connaître toutes les informations de chaque endpoint

  • d'exécuter le endpoint,

  • de connaître sa commande curl

  • de connaître sa requête URL

Note

L'interface graphique GBox API est nommée swagger.

Après appui sur le bouton `API` de la barre de titre, l'écran suivant est affiché.
La fenêtre comprend :
../../_images/GBOX-API-01.PNG

Repère

Description

1

`Schemes` : paramètre indiquant le protocole utilisé (HTTPS)

2

Nom du compte courant : ici compte administrator

3

Bouton `Django Logout`: permet de sortir de l'interface graphique API

4

Bouton `Authorize`: permet de définir l'authentification nécessaire dans les commandes curl

5

Les endpoints sont triés par thème (tag)

6

Champ de filtration : permet de filtrer les thèmes


5.4.1.1. Détail pour un endpoint

Les informations affichées pour un endpoint sont les suivantes :

../../_images/GBOX-API-02.PNG

Repère

Description

1

Ligne de titre. Elle comprend l'action (ici GET), le nom du endpoint (ici /template), les accès (ici Administrators et Opertors), la description du endpoint

2

Bouton `Try it out` : exécute le endpoint avec les paramètres courants

10

Zone `Parameters`: affiche les paramètres optionnelles ou obligatoires pour exécuter la requête. Pour connaître les paramètres obligatoires, se référer à la zone (6).
Cette zone comprend :

9

  • Paramètre `is_default` : permet de sélectionner le template par défaut. Paramètre `true` à saisir.

8

  • Paramètre `name` : définit le nom du modèle dont les informations doivent être récupérées.
    A regarder dans la fenêtre `Model` pour le type (ici string) et si le paramètre est obligatoire (ici * = obligatoire).

7

  • Champ `ordering` : saisir le nom du champ qui sert à ordonner la réponse.

6

Zone `Responses` : zone qui affiche des informations en fonction si le bouton `Try it out` a été activé ou non

Note

Si un paramètre est obligatoire, un astérisque avec indication `required` est affiché.

Note

Dans cet écran, il n'est pas possible de saisir les paramètres. Pour cela, il faut exécuter la requête.


5.4.1.1.1. Zone `Responses` si le bouton `Try it out` est non activé

Si le bouton `Try it out` est non activé alors la zone `Responses` contient les informations de la réponse attendue :

../../_images/GBOX-API-02.PNG

Repère

Description

5

lien `Model` : en cliquant sur ce texte, la fenêtre (3) affiche le modèle de la réponse attendue

4

lien `Example Value` : en cliquant sur ce texte, la fenêtre (3) affiche un exemple de la réponse attendue avec des valeurs pour exemple.
Les valeurs sont, pour le type integer (valeur 0), pour le type string (valeur = string), pour le type boolean (valeur = true)

3

Champ de visualisation : contient le contenu sélectionné par l'option active (4) ou (5).
Un exemple de contenu est donné ci dessous.

5.4.1.1.1.1. Exemple de modèle de sortie

Le modèle de sortie donne la structure des données qui seront affichées en sortie donc après exécution de la requête.

../../_images/GBOX-API-04.PNG

Repère

Description

1

`id` : numéro du modèle. Pour ce paramètre, ses caractéristiques sont indiquées (type, titre...).

2

`name` : nom du modèle. Pour ce paramètre, ses caractéristiques sont indiquées (type, titre, longueur...).

3

`is_defaut` : champ définissant si le modèle courant est le modèle par défaut. La réponse est un booléen (valeur true/false).

4

`options` : champ définissant les options éventuelles.

5

`analysers` : champ définissant les informations de l'ensemble des moteurs.

6

`Analyser` : champ définissant les informations d'un seul moteur.


5.4.1.1.2. Exemple avec des valeurs par défaut

Dans cet exemple, les informations sont affichées avec les valeurs par défaut suivantes :

  • les paramètres de type integer sont affichés avec le nombre 0

  • les paramètres de type string sont affichés avec le texte string

  • les paramètres de type booléen sont affichés avec le texte true

../../_images/GBOX-API-05.PNG

Le repérage est le même que dans le modèle de sortie.


5.4.1.1.3. Zone `Responses` si le bouton `Try it out` est activé

Après avoir cliqué sur le bouton `Try it out`, la zone de saisie des paramètres est activée.
L'écran suivant est affiché :
../../_images/GBOX-API-06.PNG

Repère

Description

1

Bouton `Execute` : permet d'exécuter la requête avec les paramètres courants

2

Bouton `Cancel` : annule la requête

3

La zone `Responses`` n'a pas changé

Après avoir cliqué sur le bouton `Execute`, la requête est lancée et la fenêtre suivante est affichée.

../../_images/GBOX-API-07.PNG

Repère

Description

1

Bouton `Clear` : permet de revenir à l'état avant exécution

2

Zone d'affichage `Curl` : affiche la requête Curl

3

Zone d'affichage `URL` : affiche la requête URL

4

`Code` : si code 200 alors exécution ok. Si le message `code 400 Undocumented Error Bad Request` est affiché, vérifier que les paramètres obligatoires soient bien saisis.

6

`id 1` : modèle numéro 1

7

`Name  gmalcore` : moteur id 2 Gmalcore

8

`id 3` : modèle numéro 3

9

`Responses headers` : zone détaillant l'entête de la réponse

10

`Request duration` : valeur en ms de la durée de la requête