REL03-BP03 Fournir des contrats de service par API
Les contrats de service sont des accords documentés entre les producteurs d'API et les consommateurs définis dans une définition d'API lisible par machine. Une stratégie de gestion des versions permet aux consommateurs de continuer à utiliser l'API existante et de procéder à la migration de leurs applications vers la nouvelle API lorsqu'ils sont prêts. Le déploiement du producteur peut avoir lieu à tout moment tant que le contrat est respecté. Les équipes de service peuvent utiliser la pile technologique de leur choix pour satisfaire aux clauses du contrat d'API.
Résultat souhaité :
Anti-modèles courants : Les applications créées à l'aide d'architectures orientées services ou microservices peuvent fonctionner de manière indépendante tout en bénéficiant d'une dépendance intégrée à l'exécution. Les modifications apportées à un consommateur ou à un producteur d'API n'interrompent pas la stabilité de l'ensemble du système lorsque les deux parties respectent un contrat d'API commun. Les composants qui communiquent via des API de service peuvent exécuter des versions fonctionnelles indépendantes, effectuer des mises à niveau vers des dépendances d'exécution ou effectuer un basculement vers un site de reprise après sinistre (DR) avec peu ou pas d'impact mutuel. En outre, les services discrets sont capables d'évoluer de manière indépendante en absorbant la demande de ressources sans que les autres services évoluent à l'unisson.
-
Création d'API de service sans schémas fortement typés. Cela se traduit par des API qui ne peuvent pas être utilisées pour générer des liaisons d'API et des charges utiles qui ne peuvent pas être validées par programmation.
-
Absence d'adoption d'une stratégie de gestion des versions, qui oblige les utilisateurs d'API à les mettre à jour et à les publier, sous peine de défaillance lorsque les contrats de service évoluent.
-
Messages d'erreur qui divulguent les détails de l'implémentation du service sous-jacent au lieu de décrire les échecs d'intégration dans le contexte et le langage du domaine.
-
Absence d'utilisation des contrats d'API pour développer des scénarios de test et simuler des implémentations d'API afin de permettre des tests indépendants des composants du service.
Avantages liés au respect de cette bonne pratique : les systèmes distribués constitués de composants qui communiquent via des contrats de service d'API peuvent améliorer la fiabilité. Les développeurs peuvent détecter les problèmes potentiels au début du processus de développement en vérifiant les types lors de la compilation afin de s'assurer que les demandes et les réponses respectent le contrat d'API et que les champs obligatoires sont présents. Les contrats d'API fournissent une interface d'autodocumentation claire pour les API et assurent une meilleure interopérabilité entre les différents systèmes et langages de programmation.
Niveau de risque exposé si cette bonne pratique n'est pas respectée : Moyen
Directives d'implémentation
Une fois que vous avez identifié les domaines d'activité et déterminé la segmentation de votre charge de travail, vous pouvez développer vos API de service. Définissez d'abord des contrats de service lisibles par machine pour les API, puis mettez en œuvre une stratégie de gestion des versions des API. Lorsque vous êtes prêt à intégrer des services via des protocoles courants tels que REST, GraphQL ou des événements asynchrones, vous pouvez intégrer des services AWS à votre architecture pour intégrer vos composants à l'aide de contrats d'API clairement typés.
Services AWS pour les contrats d'API de service
Intégrez des services AWS, notamment Amazon API Gateway
Étapes d'implémentation
-
Tout d'abord, définissez un contrat pour votre API. Un contrat exprimera les fonctionnalités d'une API et définira des objets de données et des champs fortement typés pour l'entrée et la sortie de l'API.
-
Lorsque vous configurez des API dans API Gateway, vous pouvez importer et exporter les spécifications OpenAPI pour vos points de terminaison.
-
L'importation d'une définition OpenAPI simplifie la création de votre API et peut être intégrée à l'infrastructure AWS sous forme d'outils de code tels qu' AWS Serverless Application Model
et AWS Cloud Development Kit (AWS CDK) . -
L'exportation d'une définition d'API simplifie l'intégration aux outils de test d'API et fournit aux consommateurs de services une spécification d'intégration.
-
-
Vous pouvez définir et gérer les API GraphQL avec AWS AppSync en définissant un fichier de schéma GraphQL afin de générer votre interface de contrat et de simplifier l'interaction avec des modèles REST complexes, plusieurs tables de base de données ou des services existants.
-
Les projets AWS Amplify
intégrés à AWS AppSync génèrent des fichiers de requête JavaScript fortement typés à utiliser dans votre application ainsi qu'une bibliothèque cliente AWS AppSync GraphQL pour les tables Amazon DynamoDB . -
Lorsque vous consommez des événements de service provenant d'Amazon EventBridge, les événements adhèrent à des schémas qui existent déjà dans le registre des schémas ou que vous définissez à l'aide de la spécification OpenAPI. Avec un schéma défini dans le registre, vous pouvez également générer des liaisons client à partir du contrat de schéma afin d'intégrer votre code aux événements.
-
Extension ou gestion des versions de votre API. L'extension d'une API est une option plus simple lorsque vous ajoutez des champs qui peuvent être configurés avec des champs facultatifs ou des valeurs par défaut pour les champs obligatoires.
-
Les contrats basés sur JSON pour des protocoles tels que REST et GraphQL peuvent être une bonne solution pour l'extension de contrat.
-
Les contrats basés sur XML pour des protocoles tels que SOAP doivent être testés auprès des consommateurs de services afin de déterminer la faisabilité d'une extension du contrat.
-
-
Lors de la gestion des versions d'une API, pensez à implémenter la gestion des versions par proxy lorsqu'une façade est utilisée pour prendre en charge les versions afin que la logique puisse être maintenue dans une base de code unique.
-
Avec API Gateway vous pouvez utiliser les mappages de demandes et de réponses afin de simplifier l'absorption des modifications du contrat en établissant une façade permettant de fournir des valeurs par défaut pour les nouveaux champs ou de supprimer les champs retirés d'une demande ou d'une réponse. Avec cette approche, le service sous-jacent peut gérer une base de code unique.
-
Ressources
Bonnes pratiques associées :
Documents connexes :
Exemples connexes :
Vidéos connexes :
Outils associés :
