Docs

APIs

À quoi sert cet écran

La section APIs liste les APIs enregistrées dans le catalogue et affiche leurs définitions. Elle répond à « qu’est-ce que je peux appeler, et qu’est-ce que cela attend ? » sans avoir à retrouver l’équipe propriétaire au préalable.

Avant de commencer

Pour faire ceci Il vous faut
Parcourir les APIs l’accès en lecture au catalogue

Les APIs sont des entités de catalogue, enregistrées comme les composants — voir Settings › Development › Projects.

Ouvrir l’écran

  1. Explore › APIs dans la barre latérale.

URL directe : /api-docs

L’interface

📸 Capture d’écran : La liste des APIs avec une API ouverte. Repères : (1) la liste, (2) la colonne propriétaire, (3) la vue de la définition, (4) les consommateurs et fournisseurs.

# Élément Ce qu’il fait Quand l’utiliser
1 Liste des APIs Toutes les APIs enregistrées Parcourir
2 Propriétaire L’équipe responsable Avant d’en dépendre
3 Définition La spécification, rendue Comprendre comment l’appeler
4 Consommateurs / fournisseurs Quels composants l’utilisent ou la servent Juger si un changement est sûr

Procédures

Comprendre comment appeler une API

  1. Explore › APIs, trouvez-la.
  2. Lisez la définition.
  3. Notez le propriétaire avant de construire dessus : une API sans propriétaire est une API dont les changements arriveront sans prévenir.

Vérifier qui consomme une API avant de la modifier

Ouvrez l’API et lisez ses consommateurs. Confirmez ensuite dans Architecture, qui montre les mêmes relations sous forme de graphe et rend visibles les consommateurs indirects.

Scénario

Vous vous apprêtez à introduire un changement cassant sur une API que vous possédez.

  1. Explore › APIs, ouvrez votre API.
  2. Lisez les consommateurs. C’est la liste des équipes à qui vous devez une conversation.
  3. Ouvrez Architecture et recherchez l’API, pour attraper les consommateurs qui l’atteignent indirectement.
  4. Vérifiez le propriétaire de chaque consommateur dans le Catalogue. Les consommateurs sans propriétaire sont les plus dangereux : personne ne se manifestera quand vous les casserez.
  5. Seuls les consommateurs enregistrés apparaissent. Considérez la liste comme un minimum, et annoncez le changement plus largement qu’elle ne le suggère.

En cas de problème

Symptôme Cause Comment vérifier Solution
Une API n’est pas listée Elle n’est pas enregistrée comme entité de catalogue Projets Enregistrez-la
La définition ne s’affiche pas La spécification est absente ou malformée La définition de l’entité Corrigez la spec dans le dépôt source
Aucun consommateur affiché Les relations ne sont pas consignées dans le catalogue Les relations de l’entité Ajoutez-les aux entités
Le propriétaire est vide Le système propriétaire n’a pas de groupe Catalogue Renseignez le propriétaire

Pour aller plus loin