Résumé

  • RFC 9727 normalise /.well-known/api-catalog et la relation api-catalog afin qu’un éditeur déclare un ensemble d’API. Il ne certifie ni la propriété, ni l’autorisation, ni l’accessibilité, ni la surveillance de chaque cible.
  • Un catalogue racine, un renvoi vers un autre domaine et un catalogue imbriqué ont chacun leur autorité, leur contexte et leur horloge de cache. La hiérarchie est un graphe d’affirmations datées, non une chaîne automatique de confiance.
  • La suppression d’un item prouve une modification éditoriale. Le retrait opérationnel exige encore les preuves d’exposition, de trafic, de dépendances, d’exécution, de retour arrière et d’observation après coup.

L’adresse a disparu de la liste, pas forcément du réseau

RFC 9727, publié en février 2025 sur la voie normative de l’IETF, propose un mécanisme volontairement réduit. Un éditeur peut répondre à /.well-known/api-catalog, annoncer ce catalogue avec un en-tête Link et le servir au format Linkset JSON. La relation item désigne des API ; api-catalog mène à d’autres catalogues.

Cette simplicité répond à une difficulté réelle. Les API d’une organisation se retrouvent souvent dispersées entre passerelles, fichiers de déploiement, portails pour développeurs et connaissances individuelles. Le point de découverte standard transforme cette mémoire fragmentée en déclaration lisible par une machine.

Mais une déclaration n’est pas un état d’exploitation. RFC 8288 définit des liens typés ; il ne transforme pas leur cible en actif attesté. Un item valide ne dit pas si le DNS répond depuis un réseau donné, si un port écoute, si l’éditeur exploite réellement la cible, si un identifiant est accepté ou si une transaction métier aboutit. Une API absente peut, elle, rester exposée.

OWASP API9:2023 décrit précisément le risque des versions anciennes, hôtes non documentés et environnements mal distingués. RFC 9727 peut réduire cet angle mort. Il peut aussi donner une apparence trompeuse de maîtrise si la direction mesure la propreté du catalogue plutôt que l’écart entre le catalogue et le parc réel.

Chaque arête a sa propre autorité

Même un catalogue hébergé sous le domaine de l’éditeur peut lister une API partenaire, un service géré ou une ancienne entrée de compatibilité. La preuve porte sur le choix de publier la relation, pas automatiquement sur la propriété ou le contrôle de la cible.

RFC 9727 permet également de désigner un catalogue sur un autre domaine lorsque l’éditeur ne peut pas héberger la ressource well-known. Il faut alors conserver la réponse de découverte, la chaîne de redirections, les identités TLS, les horodatages et l’empreinte du contenu. Un titre inchangé ne garantit pas que l’autorité a survécu à un changement de domaine.

Les catalogues imbriqués multiplient ces frontières. Le catalogue d’un groupe peut conduire à ceux de produits, puis de régions, avec des équipes, calendriers et règles d’accès différents. RFC 9264 exige un contexte explicite parce qu’un Linkset déplacé sans son anchor peut changer de sens. Cette topologie n’est donc pas un arbre de vérité héritée, mais un graphe d’assertions situées.

Un reçu de publication utile conserverait le domaine répondant, le chemin, les redirections, le pair TLS, le moment de réponse, le type de média, le profile, l’ETag ou Last-Modified, l’empreinte du corps et chaque triplet contexte—cible—relation. Première et dernière observations ne doivent pas être rebaptisées dates de création et de suppression. Il s’agit ici d’une proposition de contrôle, pas d’une exigence supplémentaire du RFC.

Le cache et le service ne partagent pas la même horloge

RFC 9111 distingue fraîcheur, revalidation et utilisation d’une réponse périmée. Un ETag prouve qu’une représentation n’a pas changé entre deux validations ; il ne prouve pas la continuité de toutes les API listées. Une durée de fraîcheur longue peut retarder une suppression urgente. Une durée courte augmente les consultations de l’origine sans corriger un catalogue mal entretenu.

Il faut séparer l’heure voulue par l’éditeur, celle de la réponse d’origine, celle de la validation ou réutilisation par un cache, celle d’une modification de passerelle et celle de l’observation. « Absent du catalogue à 14 heures » n’est vérifiable qu’avec la réponse et le chemin de cache ; ce n’est pas « arrêté à 14 heures ».

RFC 9727 recommande justement de surveiller disponibilité et performances du catalogue, de rapprocher sa consultation des appels d’API ultérieurs, d’enlever les entrées obsolètes, de contrôler syntaxe et règles métier, et d’intégrer sa mise à jour au cycle de livraison. Il précise surtout que le catalogue complète un cadre de gestion des API au lieu de le remplacer.

Un catalogue disponible peut décrire une API en panne

Une sonde peut charger le well-known, valider le JSON et parcourir tous les sous-catalogues pendant qu’un item échoue. À l’inverse, l’origine du catalogue peut être indisponible tandis que des clients connaissant déjà les URL continuent à travailler.

La relation status de RFC 8631 peut conduire vers une ressource d’état, mais ne fusionne pas cette page, le catalogue et l’API en une seule mesure. Une connexion TCP, une réponse HTTP et une opération métier authentifiée sont trois observations. Toute assertion de santé doit nommer la transaction, le point d’observation, le contexte d’identité et la période.

RFC 9727 avertit aussi qu’un catalogue peut révéler des API internes. TLS, revue, droits d’écriture minimaux, limitation de débit et contrôle d’accès protègent la publication. Ils ne démontrent pas qu’une cible interne est inaccessible depuis l’extérieur. Lire le catalogue ne confère pas davantage le droit d’appeler ses cibles. Accès au catalogue et exposition des endpoints restent deux tests.

Effacer une ligne n’éteint pas un service

L’audit d’un catalogue peut aider à repérer des « API zombies », non maintenues, non surveillées ou non corrigées. C’est précisément parce que l’état administratif et le code en fonctionnement se sont séparés. La découverte ouvre une enquête ; elle n’en signe pas la clôture.

Supprimer un item peut être une correction, un transfert vers un autre catalogue, une dissimulation temporaire, un remplacement ou un retrait planifié. L’acte ne ferme aucun listener, ne révoque aucun secret, ne supprime aucun DNS, ne vide aucune file et ne met à jour aucun client inconnu. La présence continue n’atteste pas non plus le maintien du support.

Un reçu de retrait doit joindre la dernière version du catalogue et la décision autorisée aux modifications DNS, routage, répartiteur et passerelle ; aux environnements concernés ; aux propriétaires et traitements dépendants ; au trafic, avec sa fenêtre et ses angles morts ; aux identifiants et flux d’intégration ; à l’accusé d’exécution ; au responsable d’exception et de retour arrière ; enfin aux sondes postérieures. Un traitement trimestriel ou un partenaire hors mesure doit rester « inconnu », pas devenir zéro.

L’article BTW consacré à Deprecation et Sunset couvre déjà la migration des clients. La thèse présente est plus étroite : la disparition d’une relation de catalogue n’est pas une preuve d’exécution. Un serveur peut répondre après sa suppression et disparaître avant que son lien soit retiré. Il faut conserver ce désaccord au lieu de réécrire l’historique.

Sources

Spécifications et registres : RFC 9727, notice RFC Editor, IETF Datatracker, registre IANA well-known, registre IANA des relations, RFC 9264, RFC 8288, RFC 8615, RFC 8631, RFC 9111, RFC 9745, RFC 8594, OWASP API9:2023.

Cadre analytique attribué : Lu Heng, Note 64, primauté du code en fonctionnement, raison d’être de BTW.