Aller au contenu principal

Référence API

L'écran Référence API vous permet d'ouvrir la documentation interactive de l'API Control Plane (Swagger UI, ReDoc, OpenAPI JSON) et de lire les métadonnées que l'API publie sur elle-même. Chemin dans le portail : /developer/api. Il sert aux développeurs qui appellent l'API directement ou génèrent un client.

Ce que montre l'écran​

  • Trois cartes, chacune ouvrant un nouvel onglet du navigateur :
    • Swagger UI : l'adresse <url-api>/docs.
    • ReDoc : l'adresse <url-api>/redoc.
    • OpenAPI JSON : l'adresse <url-api>/openapi.json. <url-api> est l'adresse de l'API Control Plane configurée dans le portail. Chaque carte affiche l'adresse complète sous son libellé.
  • Métadonnées de l'API : la réponse JSON de GET /v1/meta.

Actions​

Bouton ou actionCe qu'il faitAppel APIRôles
Carte Swagger UIOuvre la documentation interactive dans un nouvel onglet.Aucun (lien)Tout utilisateur connecté
Carte ReDocOuvre la documentation ReDoc dans un nouvel onglet.Aucun (lien)Tout utilisateur connecté
Carte OpenAPI JSONOuvre le document OpenAPI dans un nouvel onglet.Aucun (lien)Tout utilisateur connecté
Réessayer (état d'erreur de Métadonnées de l'API)Relit les métadonnées.GET /v1/metaTout utilisateur connecté

Rôles​

Le portail ne demande aucun rôle sur cet écran. Les liens ouvrent seulement la documentation ; chaque appel lancé depuis Swagger UI passe toujours par l'authentification et les rôles de chaque route.

Tâches courantes​

Essayer une route depuis Swagger UI​

  1. Ouvrir Swagger UI. Il liste chaque route avec son corps. Cliquez sur la carte Swagger UI. Résultat attendu : un nouvel onglet s'ouvre sur <url-api>/docs. En cas d'échec : le navigateur a bloqué l'onglet, ou l'API n'est pas joignable à cette adresse.
  2. S'authentifier. Chaque route /v1 demande un jeton ou une clé d'API. Utilisez la boîte d'autorisation de Swagger UI avec votre jeton. Résultat attendu : les routes répondent au lieu de 401. En cas d'échec : créez une clé d'API sur la page des clés d'API.
  3. Appeler la route. Remplissez les paramètres et lancez-la. Résultat attendu : la réponse de la route. En cas d'échec : lisez le code d'erreur ; 403 signifie qu'un rôle manque.

Télécharger le document OpenAPI​

  1. Ouvrir le document. Cliquez sur OpenAPI JSON. Résultat attendu : le document JSON s'ouvre. En cas d'échec : vérifiez l'adresse affichée sous la carte.
  2. L'enregistrer. Enregistrez la page depuis le navigateur et donnez-la à votre générateur de client. Résultat attendu : un client de l'API. En cas d'échec : comparez avec la copie publiée docs/api/openapi-v1.json.

Dépannage​

SymptômeCauseCorrection
État d'erreur dans Métadonnées de l'APIGET /v1/meta a échoué.Cliquez sur Réessayer, puis vérifiez que le Control Plane tourne.
« L'API Control Plane est injoignable »L'API est arrêtée ou l'adresse de l'API du portail est fausse.Vérifiez le Control Plane et le paramètre NEXT_PUBLIC_EAI_API_URL du portail.
Une carte ouvre une page blancheL'adresse de l'API dans le portail n'est pas l'adresse publique.Corrigez l'adresse de l'API du portail.

Pages liées​