Ce qu'un portail développeurs API doit afficher pour une intégration partenaire, au-delà du développeur individuel
Un portail pensé pour un développeur individuel met en avant une documentation vivante, un bac à sable et des jetons en self-service. Nous avons détaillé cette couche dans un article précédent sur l'adoption des portails développeurs. Elle reste nécessaire, mais elle ne répond pas aux questions d'un partenaire grand compte, qui engage son propre système de production sur la durée.
Les trois sections suivantes détaillent chacun de ces sujets, à partir de politiques publiées par des plateformes API publiques.
Le périmètre d'authentification à publier dans le portail API
Le grant client credentials : un mécanisme pour une authentification système à système
La RFC 6749, qui définit le protocole OAuth 2.0, décrit un mécanisme appelé grant « client credentials ». Un client, entendu ici comme un système technique agissant pour son propre compte, obtient un jeton d'accès avec ses seuls identifiants, pour accéder à des ressources sous son propre contrôle ou arrangées au préalable avec le serveur d'autorisation (RFC 6749). C'est le mécanisme à documenter dans un portail pour une intégration où un service appelle un autre service, sans utilisateur humain qui se connecte.
Pour les intégrations qui combinent un système partenaire et un accès front-end, nous avons détaillé la mise en œuvre côté Drupal headless dans un article sur l'authentification sécurisée entre front et API.
Le type de client que ce grant exige, et ce qu'il ne couvre pas
La même RFC restreint ce grant aux clients confidentiels, c'est-à-dire capables de garder leurs identifiants secrets, typiquement un service côté serveur (RFC 6749). Un client public, une application installée ou exécutée dans un navigateur, ne peut pas garantir cette confidentialité et n'est donc pas couvert par ce mécanisme.
Votre portail gagne à préciser ce point dès la page d'authentification : le grant client credentials couvre l'identité technique d'un système partenaire, pas la sécurité générale de l'API ni la création ou la rotation des clés. Ces deux derniers sujets restent, à notre connaissance, sans référentiel officiel généraliste équivalent à la RFC OAuth : à traiter au cas par cas avec chaque partenaire plutôt qu'à promettre dans une page générique.
La cadence de version et le préavis à publier dans le portail API
Des versions régulières sans rupture, des ruptures annoncées à part
Depuis sa version datée du 30 septembre 2024 (« acacia »), Stripe publie de nouvelles versions de son API chaque mois sans rupture de compatibilité, et réserve les changements cassants à deux versions majeures par an (documentation Stripe sur les versions d'API). Un intégrateur peut ainsi monter de version mensuelle sans modifier son code, et sait à l'avance que seule une version majeure nommée demande une revue de son intégration.
C'est un référentiel externe, propre à Stripe, pas une politique de DrupaLabs ni une attente démontrée de l'ensemble de vos partenaires. Il illustre une structure possible : séparer clairement les versions mineures, sans risque, des versions majeures, qui demandent une action du partenaire.
Le préavis de dépréciation à afficher, et ses deux cas distincts
Dans ses conditions Google Cloud, Google s'engage à notifier ses clients au moins douze mois avant deux situations distinctes : l'arrêt d'un service disponible en disponibilité générale, sauf remplacement par un service matériellement similaire, et une modification substantielle d'une API qui casse la compatibilité, sans cette exception de remplacement (conditions Google Cloud). Cet engagement ne s'applique pas en cas d'obligation légale, de risque de sécurité matériel, de charge économique ou technique substantielle, ni à certains services exclus de son périmètre.
Deux cas, deux lectures différentes pour un partenaire : l'arrêt d'un service peut arriver plus tôt si un remplacement équivalent est proposé, une rupture d'API ne bénéficie pas de cette porte de sortie. Un portail qui affiche un préavis sans distinguant ces deux cas laisse le partenaire deviner lequel s'applique à sa situation, et sous quelles exceptions.
Le comportement de nouvelle tentative des webhooks à publier dans le portail API
Ce que couvre une re-livraison automatique documentée, en production et en sandbox
En production, Stripe retente la livraison d'un événement webhook pendant trois jours au maximum, avec un délai croissant entre chaque tentative. Dans son environnement de sandbox, Stripe effectue trois tentatives sur quelques heures pour les livraisons créées dans cet environnement (documentation Stripe sur les webhooks). Ce sont deux comportements distincts, documentés séparément pour chaque environnement.
Un partenaire qui intègre vos webhooks a besoin de savoir, pour chaque environnement, combien de temps votre système retente une livraison avant d'abandonner, et à quel rythme. Sans cette information publiée, il construit sa propre logique de relance en devinant la vôtre, ce qui fait construire deux fois la même logique de relance, et multiplie les occasions de désynchronisation en cas d'incident.
Une grille de départ, à confronter aux retours de vos propres partenaires
Trois politiques à publier dans un portail API destiné à des intégrations partenaires : le périmètre d'authentification accepté, avec sa distinction entre client confidentiel et client public ; la cadence de version et son préavis de dépréciation, avec ses cas et ses exceptions ; le comportement de nouvelle tentative des webhooks, détaillé par environnement.
Cette grille vient d'un constat sur des politiques publiées par des plateformes externes. Avant de la publier telle quelle, nous vous recommandons de la confronter aux retours de vos propres partenaires : ce qui leur manque aujourd'hui dans votre documentation, et ce qu'ils négocient encore par e-mail parce que votre portail ne le dit pas. Un diagnostic de votre portail actuel, mis en regard de cette grille, montre où se situent les écarts avant de les combler.
Demander un diagnostic.