5.7.1. Présentation de l'interface API

L'interface API permet :

Note

L'interface graphique API est nommée swagger.

L'accès à cette interface est disponible dans le barre de titre de l'interface principale.

Après appui sur le bouton (4) `API` de la barre de titre, l'écran suivant est affiché.

La fenêtre comprend :

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

Dans cette interface, l'ensemble des endpoints API sont disponibles et utilisables.

L'utilisation des différents endpoints est soumise aux mêmes droits que dans les interfaces web du GCenter.

Note

Une fonctionnalité nécessitant des droits administrateurs ne pourra être utilisée par un utilisateur n'ayant que les droits opérateurs.

5.7.1.1. Détail pour un endpoint

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

Repère	Description
1	Ligne de titre. Elle comprend l'action (ici GET), le nom du endpoint (ici /api/gcaps), 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
8	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 les paramètres nécessaire à l'API sélectionné. Dans cet exemple, il y en a deux : le numéro de pages et le nombre de résultats par page.
7	Paramètre `page` : permet de saisir un numéro de page. Cet exemple dépend de l'API
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.

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

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.

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.

Repère	Description
1	`count` : nombre. Pour ce paramètre, ses caractéristiques sont indiquées (entier).
2	`results` : résultats attendus
3	`GcapReadOnly` : Paramètres du GCap. Pour chaque paramètre (id, fqdn,is_paired...), les caractéristiques sont affichées

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

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

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é :

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.

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	Zone d'affichage `Server response` : affiche la réponse du serveur à la requête. Elle comprend les élements suivants
5	`Code` : si code 200 alors l'exécution est ok. Si le message `code 400 Undocumented Error Bad Request` est affiché, vérifier que les paramètres obligatoires soient bien saisis.
6	`Responses body` : dans cette partie, sont affichées les informations demandées
7	`Responses headers` : zone détaillant l'entête de la réponse
8	`Request duration` : valeur en ms de la durée de la requête