Découverte

La découverte regroupe ce qui permet à un développeur de trouver une API, de comprendre ce qu’elle fait et de réussir un premier appel sans solliciter personne. Le pilier se mesure par un seul indicateur, le délai entre l’arrivée du développeur et son premier appel réussi, et il conditionne la valeur de tout le reste : une API introuvable n’est appelée par personne.

Quatre éléments

Le catalogue. La liste de ce qui existe, avec le propriétaire et l’état de cycle de vie. Une API en dépréciation doit se signaler avant qu’un nouveau consommateur l’adopte.

Le contrat. Une description OpenAPI, ou AsyncAPI pour l’événementiel, qui reflète le comportement réel. Un contrat inexact coûte plus cher qu’un contrat absent : l’erreur se découvre à l’intégration au lieu de se voir à la lecture.

L’environnement d’essai. Un jeton de test obtenu sans démarche, des données de démonstration, un appel exécutable depuis la documentation. Sans cela, le développeur intègre à l’aveugle et les écarts se découvrent en recette.

Le rattachement. Qui possède l’API, qui répond aux questions, où signaler un problème. C’est l’information la plus demandée et la plus rarement publiée.

Le catalogue se génère, ou il ment

Un catalogue rempli à la main diverge de la réalité en quelques mois. La seule version durable se génère depuis la source de vérité : le contrat vit dans le dépôt du service, la publication au catalogue est une étape de la chaîne d’intégration, le catalogue reflète ce qui est déployé. Cette chaîne est décrite dans industrialiser.

Générer le catalogue depuis le trafic observé sur la gateway est l’erreur symétrique : on obtient la liste de ce qui est appelé, pas de ce qui est offert. Les deux listes diffèrent, et l’écart entre elles est justement une information de gouvernance.

Décrire n’est pas documenter

Un contrat OpenAPI donne les chemins, les types et les codes de retour. Trois choses manquent presque toujours, et ce sont celles que les intégrateurs cherchent :

• un exemple d’appel complet, avec des valeurs réalistes, copiable tel quel.
• la sémantique des erreurs : ce qu’un 409 signifie sur cette opération précise, et ce que l’appelant doit faire.
• les limites d’usage : quotas, pagination, tailles maximales.

Leur place est dans le contrat lui-même, en descriptions et en exemples, pas dans une page séparée qui divergera.

Le délai jusqu’au premier appel réussi

L’indicateur agrège tout ce qui bloque réellement : qualité du contrat, obtention des identifiants, disponibilité du bac à sable. Il est difficile à améliorer artificiellement, ce qui en fait une bonne base d’objectif.

Au-delà de la journée, la cause n’est plus outillable : c’est un circuit de validation humain, et il se traite comme tel.

La recherche

À quelques dizaines d’API, la navigation par domaines cesse de fonctionner : le développeur cherche un besoin, pas un organigramme. La recherche doit porter sur le contenu des contrats, champs et descriptions compris. Chercher IBAN doit remonter les API qui en manipulent un, même si aucune ne porte ce mot dans son titre. Beaucoup de portails indexent le titre et la description de l’API, pas le contenu du contrat. Le point mérite une vérification en démonstration, contrats réels chargés.