Gestion des API : portail, sécurité, versions
Une organisation qui expose plus de quelques API doit les gérer comme un produit : un point d'entrée, une documentation, des règles d'accès, une politique de versions. Sans cela, chaque API devient un cas particulier et chaque changement, un risque.
La première API d’une organisation est souvent un projet : un besoin, une équipe, un service publié. La dixième pose un autre problème. Chaque API a sa documentation, son mode d’authentification, sa façon de signaler les erreurs ; personne ne sait exactement qui les utilise ; une modification anodine casse l’application d’un partenaire. L’API management, ou gestion des API, désigne l’ensemble des outils et des règles qui remettent de l’ordre : un point d’entrée commun, un portail pour ceux qui les utilisent, une politique de sécurité et de versions.
Trois piliers, pas un logiciel
Le marché vend des plateformes d’API management complètes. Elles regroupent trois fonctions qu’il vaut mieux penser séparément, parce qu’elles ne relèvent pas des mêmes personnes.
La passerelle reçoit toutes les requêtes, vérifie l’identité de l’appelant, applique les quotas, journalise, puis transmet au service concerné. Elle relève de l’exploitation et de la sécurité.
Le portail présente le catalogue des API, leur documentation, les conditions d’usage, et permet aux développeurs d’obtenir leurs accès. Il s’adresse aux utilisateurs, internes ou externes.
La gouvernance fixe les règles communes : conventions de conception, format de documentation, politique de versions, revue avant publication. Elle relève d’une petite équipe transverse, et c’est le pilier le plus souvent oublié.
Le portail : ce que le développeur doit trouver
Un développeur qui découvre une API se pose toujours les mêmes questions, dans le même ordre. Le portail doit y répondre sans qu’il ait besoin d’écrire à quelqu’un.
- À quoi sert cette API, et quelles données expose-t-elle ?
- Comment obtenir un accès, et sous quelles conditions (licence, quotas, données personnelles) ?
- Comment s’authentifier, avec un exemple qui fonctionne ?
- Quelles sont les ressources, les paramètres, les erreurs possibles ?
- Existe-t-il un environnement de test avec des données fictives ?
- Quelle est la version courante, et quand la précédente sera-t-elle retirée ?
- Qui contacter en cas de problème, et quel est l’état du service ?
La spécification OpenAPI est devenue le format de référence pour décrire les API REST. Écrite avant le code, elle sert à la fois de contrat, de documentation et de base pour les tests. Un portail alimenté par les spécifications reste à jour ; un portail rédigé à la main dérive en quelques mois.
La sécurité : là où les API sont vraiment attaquées
Les failles les plus fréquentes des API ne viennent pas d’un manque de chiffrement. L’OWASP, dans son classement des risques de sécurité des API (édition 2023), place en tête les défauts d’autorisation : un utilisateur authentifié qui accède aux données d’un autre en changeant simplement un identifiant dans l’adresse. La passerelle ne peut pas détecter ce problème seule ; il se règle dans le service, objet par objet.
Les règles de base sont connues :
Authentifier chaque appel. OAuth 2.0 et OpenID Connect pour les accès qui engagent un utilisateur ; certificats ou jetons de client pour les échanges entre machines. Jetons à durée courte, portées limitées au strict nécessaire.
Autoriser chaque objet. Vérifier à chaque requête que l’appelant a le droit d’accéder à cette ressource précise, pas seulement à ce type de ressource.
Ne renvoyer que le nécessaire. Une API qui renvoie l’objet complet en comptant sur l’application pour masquer certains champs expose ces champs à quiconque lit la réponse.
Limiter et surveiller. Quotas par client, limitation du débit, journalisation exploitable, alertes sur les comportements anormaux. L’inventaire des API exposées fait partie de la sécurité : une ancienne version oubliée est une porte ouverte.
Le risque le plus difficile à voir est celui des API que personne ne gère plus : une version ancienne laissée en ligne, un service de test exposé, une API créée par un prestataire et jamais documentée. Un inventaire régulier, rapproché des journaux de la passerelle, est le seul remède.
Les versions : promettre peu, tenir longtemps
Toute API évolue. La question est de savoir si l’évolution casse les applications qui l’utilisent. Une politique de versions écrite distingue les changements compatibles (ajouter un champ facultatif, une nouvelle ressource) et les changements incompatibles (supprimer un champ, changer un type, modifier une règle). Seuls les seconds justifient une nouvelle version majeure.
| Méthode | Principe | Avantage | Limite |
|---|---|---|---|
| Version dans l’adresse | /v1/, /v2/ |
Lisible, simple à router dans la passerelle | Incite à multiplier les versions |
| Version dans un en-tête | En-tête de requête dédié ou type de média | Adresses stables | Moins visible, plus difficile à tester à la main |
| Évolution sans version | Seuls des changements compatibles sont autorisés | Aucune migration pour les utilisateurs | Exige une grande discipline de conception |
Quelle que soit la méthode, le cycle de vie doit être annoncé dès la publication : durée minimale de maintien d’une version, délai de préavis avant retrait, canal d’information des utilisateurs. L’en-tête HTTP Sunset (RFC 8594) permet d’indiquer dans les réponses elles-mêmes la date de retrait prévue. Les journaux de la passerelle montrent qui utilise encore l’ancienne version, ce qui permet de prévenir directement les retardataires.
Une API publiée est une promesse faite à des gens qu’on ne connaît pas encore.
Par où commencer
Une organisation qui a déjà plusieurs API sans gestion commune peut avancer par paliers. D’abord, l’inventaire : quelles API, qui les maintient, qui les utilise. Ensuite, des conventions écrites et une spécification OpenAPI pour chaque API. Puis une passerelle devant les API exposées à l’extérieur, avec une authentification commune. Le portail vient enfin, quand le catalogue est assez stable pour être présenté. Inverser l’ordre, en achetant d’abord une plateforme complète, conduit souvent à un outil coûteux qui expose le même désordre.
Notre guide pour relier ses logiciels proprement par API traite la conception elle-même. Les équipes déployées de DOSOBE peuvent prendre en charge l’inventaire, les conventions et la mise en place de la passerelle, puis transmettre la gouvernance aux équipes internes.
Pour approfondir : Gouvernance & traçabilité
Questions fréquentes
Faut-il une passerelle d'API pour quelques services ?
Pas forcément au début. Elle devient utile dès que plusieurs équipes publient des API, que des partenaires extérieurs s'y connectent ou qu'il faut appliquer des quotas et une authentification commune. Avant, une bonne documentation et une politique de versions suffisent souvent.
OAuth 2.0 ou clés d'API ?
Les clés d'API identifient une application ; elles conviennent pour des données peu sensibles et des accès de machine à machine simples. Dès qu'un accès porte sur les données d'un utilisateur ou demande des droits fins, OAuth 2.0 avec des jetons à durée courte et des portées limitées est la référence.
Combien de versions d'une API faut-il maintenir en parallèle ?
Le moins possible : en général la version courante et la précédente, pendant une période de transition annoncée. Au-delà, le coût de maintenance et le risque de sécurité augmentent sans bénéfice pour les utilisateurs.