Recetter une API métier commune à deux sites avec un contrat OpenAPI

Dans le cloud public, une organisation peut devenir dépendante des produits et services de fournisseurs particuliers : changer de technologie ou de fournisseur devient alors difficile, long et disproportionnellement coûteux. Bien que cette dépendance soit généralement considérée comme à éviter, ses avantages dans le cloud peuvent souvent l’emporter sur ses inconvénients. [1]

Quand plusieurs clients aux besoins différents consomment le même backend, une API conçue sans discipline peut accumuler les cas particuliers et les endpoints. L’approche API-first conduit à concevoir l’API pour le cas général, plutôt que pour le seul premier consommateur. [2]

API‑first n’est pas un choix de framework mais une décision de séquençage : rédiger le contrat avant d’écrire le code change l’organisation du travail, le rythme de livraison et la maintenabilité en faisant du contrat le point de départ de la conception. [2]

Dans une approche code-first, le développeur écrit la logique backend et l’API en découle : ses routes, paramètres et formes de réponse reflètent les choix d’implémentation. Dans une approche API-first, le contrat d’API constitue le point de départ. [2]

Si une API est destinée à des développeurs externes, comme produit ou comme interface d’intégration pour des partenaires, ces développeurs s’appuient sur son contrat, faute d’accès au code source. Un contrat API-first bien conçu et publié via Swagger UI ou Redoc permet aux partenaires de s’intégrer sans solliciter l’équipe d’ingénierie pour chaque question. [2]

Il convient de conserver la propriété des données détenues par des tiers et l’accès à celles-ci. Dans le cloud public, les fournisseurs proposent généralement des contrats renouvelables à l’usage : même si l’on peut en théorie cesser d’utiliser leurs services à tout moment, cela peut être difficile en pratique. [1]

Si une organisation choisit des mesures techniques pour réduire sa dépendance à un fournisseur cloud, leur forme dépend du déploiement : avec un fournisseur unique, elle devrait prévoir un plan de contingence en cas de changement de stratégie ; en multicloud, elle doit planifier le déplacement éventuel de composants ou de services vers d’autres hébergements et peut tester régulièrement cette possibilité. [1]

Une stratégie de sortie doit mettre en balance l’impact d’un changement de fournisseur et l’intérêt de rester. Pour les produits SaaS, le choix de standards et de formats ouverts permet de garder la maîtrise des données et la possibilité de les exporter vers un nouvel environnement ; pour les services PaaS et IaaS, les pistes citées comprennent l’open source lorsque c’est possible, le faible couplage des composants et les outils d’infrastructure as code utilisables sur plusieurs plateformes cloud. [1]

Dans la démarche décrite, la spécification OpenAPI est rédigée avant toute implémentation et définit les endpoints, les schémas de requête et de réponse ainsi que les réponses d’erreur. [2]

À partir d’une spécification partielle, un serveur mock peut fournir des réponses conformes au schéma. Prism peut être lancé depuis un fichier OpenAPI avec la commande « npx @stoplight/prism-cli mock openapi.yaml » ; l’équipe frontend dispose ainsi d’une API simulée contre laquelle développer, sans backend réel. [2]

L’équipe backend implémente les endpoints conformément à la spécification : celle-ci sert de critère d’acceptation, et un endpoint est considéré comme achevé lorsqu’il se comporte exactement comme le décrit le contrat. [2]

Dans la configuration décrite pour les plugins MCP et les plugins API issus d’un document OpenAPI, Microsoft Entra SSO permet aux utilisateurs de s’authentifier avec leurs identifiants Entra ID ; le serveur MCP ou l’API doit utiliser Entra ID pour contrôler l’accès. Les mêmes étapes s’appliquent aux deux types de plugins, sauf exceptions signalées : enregistrer une application Entra pour sécuriser le serveur ou l’API, créer la configuration d’authentification, mettre à jour l’enregistrement et ajouter à l’API la nouvelle audience du jeton. [3]

Le serveur MCP ou l’API doit être sécurisé par un enregistrement d’application Entra. S’il n’en existe pas déjà un, il faut enregistrer une application dans le centre d’administration Microsoft Entra, puis relever son identifiant client pour créer la configuration d’authentification. [3]

Il faut mettre à jour l’API pour accepter la nouvelle Application ID URI comme audience du token et, si l’API valide l’identifiant des applications clientes, s’assurer que le client ID du Microsoft Enterprise token store (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) figure parmi les applications clientes autorisées. [3]

Pour la recette, utilisez la spécification OpenAPI pour produire des réponses simulées, définir les réponses d’erreur et vérifier que les endpoints livrés respectent le contrat. Pour un produit SaaS, privilégiez les standards et formats ouverts afin de conserver la possibilité d’exporter les données vers un nouvel environnement. Si le client est un plugin Microsoft 365 utilisant Entra SSO, vérifiez l’enregistrement de l’application, l’audience du jeton et, si l’API valide l’identifiant des applications clientes, l’autorisation du client concerné.