Le portail que personne ne visite

Le portail développeur est l'argument de vente préféré des éditeurs. C'est la partie visible de la plateforme, celle qu'on projette en comité, celle qui fait dire « on aura un store d'API comme les grands ».

Puis on regarde les statistiques de fréquentation un an après la mise en service : quelques dizaines de visites par mois, la moitié venant de l'équipe plateforme elle-même.

L'indicateur qui compte, et ce n'est pas la fréquentation

Le nombre de visites ne dit rien : un développeur qui vient trois fois parce qu'il ne trouve pas est compté trois fois. L'indicateur que suivent les éditeurs d'API dont le métier est d'être adoptés est le temps jusqu'au premier appel réussi, mesuré depuis l'arrivée sur la fiche de l'API jusqu'à la première réponse en 200 reçue par le consommateur.

Il se mesure sans instrumentation compliquée : la date de création de la souscription et la date du premier appel authentifié de ce consommateur sont toutes deux dans vos journaux. La distribution de cet écart, par API, est le seul tableau de bord de portail qui serve à quelque chose.

Ce qu'on y lit est brutal. Quand l'obtention d'une clé passe par un ticket, l'écart se compte en jours et la médiane ne descend jamais. Quand elle est en libre-service, il se compte en minutes, et les API dont l'écart reste long sont exactement celles dont la documentation est un contrat OpenAPI brut.

La version pauvre de la même mesure tient en une question posée à un développeur d'une équipe consommatrice : comment as-tu intégré la dernière API interne que tu utilises ? S'il répond « j'ai demandé sur Teams à quelqu'un qui connaissait », le portail n'est pas la voie la plus rapide, et c'est le seul critère qui compte.

Le catalogue est illisible parce qu'il est indexé sur le mauvais texte

Un développeur ne parcourt pas un catalogue, il y cherche un mot. Et le mot qu'il tape est celui de son métier : « virement », « ayant droit », « point de livraison ».

Or un catalogue alimenté par génération depuis la gateway indexe ce que contient le contrat : des chemins, des identifiants d'opération, des noms de schémas, souvent en anglais et souvent abrégés. Le vocabulaire du consommateur n'y figure nulle part. La recherche ne rend rien, le développeur conclut que l'API n'existe pas, et il la redéveloppe.

C'est la raison pour laquelle la description en langage naturel n'est pas une politesse éditoriale : c'est le seul texte sur lequel la recherche peut fonctionner. Une fiche utile nomme le domaine métier, les synonymes employés en interne, et le système d'origine de la donnée, qui est souvent le seul terme que le demandeur connaisse.

La règle qui décide de tout : une seule porte

Les portails qui vivent ont un point commun, et il n'est pas technique : il n'existe aucun autre moyen d'obtenir un accès. Pas de clé délivrée par l'équipe plateforme en message direct, pas d'exception pour un projet pressé, pas de compte de service créé à la main pour dépanner.

Chaque dérogation est un raccourci qui devient la norme. Tant qu'obtenir une clé autrement demande moins d'effort, les équipes se passent les clés existantes sous le manteau, et la sécurité repose sur des identifiants partagés que personne ne saura révoquer.

Deux conditions rendent cette règle tenable, et il faut les poser avant elle.

Un propriétaire, dont c'est le travail de faire vivre le catalogue, de relire les documentations et de refuser une publication indigente. Sans ce rôle, le portail devient un débarras de contrats OpenAPI.

Et un standard de publication opposable, qui n'accepte pas une API sans description en langage naturel, exemples d'appel et contact d'équipe. C'est une règle de gouvernance qui s'automatise très bien au moment de la publication.

Un portail interne n'est pas un portail public

L'erreur de conception la plus fréquente est de reprendre les codes d'un portail public, qui sont ceux d'un site de vente : une page d'accueil, des arguments, un parcours d'inscription.

Le consommateur interne n'a rien à acheter et n'a pas besoin d'être convaincu. Il a besoin de trois informations que les portails publics ne portent jamais, parce qu'elles n'auraient aucun sens à l'extérieur : quelle équipe possède cette API et où on lui parle, quel est son niveau d'engagement réel, et si elle a le droit d'être appelée depuis le contexte où l'on se trouve. La dernière est celle qui manque le plus : un développeur qui ignore si une API interne est ouverte à son domaine ouvrira un ticket, et on retombe sur le délai.

À l'inverse, tout ce qui relève de la mise en avant commerciale, du versement de plaquettes et du parcours d'essai anonyme est du travail perdu en interne.

Ce qui échoue vraiment

Le portail est le composant le moins technique de la plateforme, et c'est exactement pour cela qu'il échoue le plus souvent : personne ne se sent responsable d'un problème qui n'est pas technique. Une équipe plateforme sait diagnostiquer une latence, elle n'a ni le mandat ni le réflexe de refuser une documentation médiocre.

C'est une décision d'organisation, pas d'outillage, et elle se prend avant l'achat du produit plutôt qu'un an après sa mise en service.