Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Implémentez la gestion des versions d'API basée sur les chemins en utilisant des domaines personnalisés dans Amazon API Gateway *Corey Schnedl, Marcelo Barbosa, Mario Lopez Martinez, Anbazhagan Ponnuswamy, Gaurav Samudra et Abhilash Vinod, Amazon Web Services* ## Résumé Ce modèle montre comment vous pouvez utiliser la fonctionnalité de [mappage d'API](https://docs.aws.amazon.com/apigateway/latest/developerguide/rest-api-mappings.html) des [domaines personnalisés](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-custom-domains.html) pour implémenter une solution de gestion des versions d'API basée sur les chemins pour Amazon API Gateway. Amazon API Gateway est un service entièrement géré que vous pouvez utiliser pour créer, publier, gérer, surveiller et sécuriser APIs à n'importe quelle échelle. En utilisant la fonctionnalité de domaine personnalisé du service, vous pouvez créer des noms de domaine personnalisés plus simples et plus intuitifs URLs que vous pouvez fournir aux utilisateurs de vos API. Vous pouvez utiliser les mappages d'API pour connecter les étapes d'API à un nom de domaine personnalisé. Après avoir créé un nom de domaine et configuré les enregistrements DNS, vous utilisez les mappages d'API pour envoyer du trafic vers vous APIs via votre nom de domaine personnalisé. Une fois qu'une API est rendue publique, les consommateurs l'utilisent. À mesure qu'une API publique évolue, son contrat de service évolue également pour refléter les nouvelles fonctionnalités et capacités. Cependant, il n'est pas judicieux de modifier ou de supprimer des fonctionnalités existantes. Toute modification importante peut avoir un impact sur les applications du client et les interrompre lors de l'exécution. Le versionnement des API est important pour éviter de rompre la rétrocompatibilité et de rompre un contrat. Vous avez besoin d'une stratégie claire pour le versionnement des API afin d'aider les consommateurs à les adopter. La gestion APIs des versions basée sur les chemins URLs est l'approche la plus simple et la plus couramment utilisée. Dans ce type de versionnement, les versions sont explicitement définies dans le cadre de l'API URIs. L'exemple suivant URLs montre comment un consommateur peut utiliser l'URI pour spécifier une version d'API pour sa demande : `https://api.example.com/api/v1/orders ` `https://api.example.com/api/v2/orders ` `https://api.example.com/api/vX/orders` Ce modèle utilise le AWS Cloud Development Kit (AWS CDK) pour créer, déployer et tester un exemple d'implémentation d'une solution de version évolutive basée sur les chemins pour votre API. AWS CDK est un framework de développement de logiciels open source permettant de modéliser et de provisionner les ressources de vos applications cloud à l'aide de langages de programmation familiers. ## Conditions préalables et limitations **Prérequis** + Un actif Compte AWS. + La propriété d'un domaine est requise pour utiliser le référentiel d'exemples de ce modèle et pour utiliser les fonctionnalités de domaine personnalisées d'Amazon API Gateway. Vous pouvez utiliser Amazon Route 53 pour créer et gérer les domaines de votre organisation. Pour plus d'informations sur l'enregistrement ou le transfert d'un domaine avec Route 53, consultez la section [Enregistrement de nouveaux domaines](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/domain-register-update.html) dans la documentation Route 53. + Avant de configurer un nom de domaine personnalisé pour une API, vous devez disposer d'un [certificat SSL/TLS](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-specify-certificate-for-custom-domain-name.html). AWS Certificate Manager + Vous devez créer ou mettre à jour l’enregistrement de ressource de votre fournisseur DNS pour le mapper au point de terminaison de votre API. Sans un tel mappage, les demandes d'API liées au nom de domaine personnalisé ne peuvent pas atteindre API Gateway. **Limites** + Un nom de domaine personnalisé doit être unique au sein d'un Région AWS ensemble Comptes AWS. + Pour configurer des mappages d’API à plusieurs niveaux, vous devez utiliser un nom de domaine personnalisé régional et la politique de sécurité TLS 1.2. + Dans un mappage d'API, le nom de domaine personnalisé et le nom de domaine mappé APIs doivent être identiques Compte AWS. + Les mappages d'API ne doivent contenir que des lettres, des chiffres et les caractères suivants : `$-_.+!*'()/` + La longueur maximale du chemin d’un mappage d’API est de 300 caractères. + Vous pouvez disposer de 200 mappages d’API à plusieurs niveaux pour chaque nom de domaine. + Vous ne pouvez APIs mapper HTTP à un nom de domaine personnalisé régional qu'avec la politique de sécurité TLS 1.2. + Vous ne pouvez pas WebSocket APIs mapper vers le même nom de domaine personnalisé qu'une API HTTP ou une API REST. + Certains Services AWS ne sont pas disponibles du tout Régions AWS. Pour connaître la disponibilité par région, consultez la section [AWS Services par région](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/). Pour des points de terminaison spécifiques, consultez [Points de terminaison de service et quotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html), puis choisissez le lien correspondant au service. **Versions du produit** + Cet exemple d'implémentation est utilisé [AWS CDK dans la TypeScript](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-typescript.html) version 2.149.0. ## Architecture Le schéma suivant montre le flux de travail de l'architecture. ![\[Flux de travail utilisant des mappages d'API et des domaines personnalisés pour implémenter une solution de gestion des versions d'API basée sur les chemins.\]](http://docs.aws.amazon.com/fr_fr/prescriptive-guidance/latest/patterns/images/pattern-img/e1b32d2b-410f-4ace-967e-f0b8aaf0304c/images/fa9f04f1-efa6-4fb1-a541-ae3da4076b00.png) Le diagramme illustre les éléments suivants : 1. L'utilisateur de l'API envoie une demande à Amazon API Gateway avec un nom de domaine personnalisé. 1. API Gateway achemine dynamiquement la demande de l'utilisateur vers une instance et une étape appropriées d'API Gateway, en fonction du chemin indiqué dans l'URL de la demande. Le tableau suivant montre un exemple de la manière dont les différents chemins basés sur des URL peuvent être routés vers des étapes spécifiques pour différentes instances d'API Gateway. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/fr_fr/prescriptive-guidance/latest/patterns/implement-path-based-api-versioning-by-using-custom-domains.html) 1. L'instance API Gateway de destination traite la demande et renvoie le résultat à l'utilisateur. **Automatisation et évolutivité** Nous vous recommandons d'utiliser des AWS CloudFormation piles distinctes pour chaque version de votre API. Avec cette approche, vous pouvez obtenir une isolation complète entre le backend vers APIs lequel la fonction de mappage d'API de domaine personnalisée peut être acheminée. L'avantage de cette approche est que différentes versions de votre API peuvent être déployées ou supprimées indépendamment sans risque de modification d'une autre API. Cette approche augmente la résilience en isolant les CloudFormation piles. En outre, il vous fournit différentes options de back-end pour votre API AWS Lambda AWS Fargate, telles que les points de terminaison HTTP et les actions de. Services AWS Vous pouvez utiliser des stratégies de branchement Git, telles que [Gitflow](https://docs.aws.amazon.com/prescriptive-guidance/latest/choosing-git-branch-approach/gitflow-branching-strategy.html), en combinaison avec des CloudFormation piles isolées pour gérer le code source déployé sur différentes versions de l'API. En utilisant cette option, vous pouvez gérer différentes versions de votre API sans avoir à dupliquer le code source pour les nouvelles versions. Avec Gitflow, vous pouvez ajouter des balises aux commits dans votre dépôt git au fur et à mesure que les versions sont effectuées. Par conséquent, vous disposez d'un instantané complet du code source associé à une version spécifique. Lorsque des mises à jour doivent être effectuées, vous pouvez extraire le code d'une version spécifique, effectuer des mises à jour, puis déployer le code source mis à jour sur la CloudFormation pile correspondant à la version majeure correspondante. Cette approche réduit le risque de rupture d'une autre version d'API, car chaque version de l'API possède un code source isolé et est déployée sur des CloudFormation piles distinctes. ## Outils **Services AWS** + [Amazon API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/welcome.html) vous aide à créer, publier, gérer, surveiller et sécuriser REST, HTTP, et ce, WebSocket APIs à n'importe quelle échelle. + [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html) vous aide à créer, à stocker et à renouveler des certificats et clés SSL/TLS X.509 publics et privés qui protègent vos AWS sites Web et vos applications. + [AWS Cloud Development Kit (AWS CDK)](https://docs.aws.amazon.com/cdk/v2/guide/home.html)est un framework de développement logiciel open source permettant de définir votre infrastructure cloud dans le code et de la provisionner via ce dernier. CloudFormation L'exemple d'implémentation de ce modèle utilise le [AWS CDK in TypeScript](https://docs.aws.amazon.com/cdk/v2/guide/work-with-cdk-typescript.html). L'utilisation du AWS CDK in TypeScript utilise des outils familiers, notamment le TypeScript compilateur Microsoft (`tsc`), [Node.js](https://nodejs.org/) et le gestionnaire de packages de nœuds (`npm`). Si vous préférez, vous pouvez utiliser [Yarn](https://yarnpkg.com/), bien que les exemples de ce modèle l'utilisent`npm`. Les modules qui composent la [bibliothèque AWS Construct](https://docs.aws.amazon.com/cdk/v2/guide/libraries.html#libraries-construct) sont distribués via le `npm ` référentiel [npmjs.org](https://docs.npmjs.com/). + [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)vous aide à configurer les AWS ressources, à les approvisionner rapidement et de manière cohérente, et à les gérer tout au long de leur cycle de vie à travers Comptes AWS et Régions AWS. + [AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) est un service de calcul qui vous aide à exécuter du code sans avoir à allouer ni à gérer des serveurs. Il exécute votre code uniquement lorsque cela est nécessaire et évolue automatiquement, de sorte que vous ne payez que pour le temps de calcul que vous utilisez. + [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html) est un service Web DNS hautement disponible et évolutif. + [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/what-is-aws-waf.html)est un pare-feu d'applications Web qui vous aide à surveiller les requêtes HTTP et HTTPS qui sont transmises aux ressources protégées de votre application Web. **Autres outils** + [Bruno](https://www.usebruno.com/) est un client de test d'API open source et convivial pour Git. + [cdk-nag](https://github.com/cdklabs/cdk-nag) est un utilitaire open source qui vérifie les meilleures pratiques des AWS CDK applications à l'aide de packs de règles. **Référentiel de code** Le code de ce modèle est disponible dans le dépôt GitHub [path-based-versioning-with-api-gateway](https://github.com/aws-samples/path-based-versioning-with-api-gateway). ## Bonnes pratiques + Utilisez un pipeline robuste d'intégration continue et de livraison continue (CI/CD) pour automatiser les tests et le déploiement de vos CloudFormation piles conçues avec le. AWS CDK Pour plus d'informations relatives à cette recommandation, consultez le guide [AWS DevOps Well-Architected](https://docs.aws.amazon.com/wellarchitected/latest/devops-guidance/devops-guidance.html). + AWS WAF est un pare-feu géré qui s'intègre facilement à des services tels qu'Amazon API Gateway. Bien qu'il AWS WAF ne s'agisse pas d'un composant nécessaire au bon fonctionnement de ce modèle de version, nous vous recommandons de l'inclure dans API Gateway en tant que bonne pratique AWS WAF de sécurité. + Encouragez les utilisateurs d'API à passer régulièrement à la dernière version de votre API afin que les anciennes versions de votre API puissent être déconseillées et supprimées efficacement. + Avant d'utiliser cette approche dans un environnement de production, implémentez un pare-feu et une stratégie d'autorisation pour votre API. + Implémentez l'accès à la gestion de vos AWS ressources Compte AWS en utilisant le modèle d'[accès avec le moindre privilège](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege). + Pour appliquer les meilleures pratiques et les recommandations de sécurité aux applications créées avec le AWS CDK, nous vous recommandons d'utiliser l'utilitaire [cdk-nag](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/check-aws-cdk-applications-or-cloudformation-templates-for-best-practices-by-using-cdk-nag-rule-packs.html). ## Épopées ### Préparez votre environnement local | Sous-tâche | Description | Compétences requises | | --- | --- | --- | | Pour cloner le référentiel. | Pour cloner le référentiel d'applications d'exemple, exécutez la commande suivante :
git clone https://github.com/aws-samples/path-based-versioning-with-api-gateway
| Développeur d’applications | | Accédez au référentiel cloné. | Pour accéder à l'emplacement du dossier du référentiel cloné, exécutez la commande suivante : 
cd api-gateway-custom-domain-versioning
| Développeur d’applications | | Installez les dépendances obligatoires. | Pour installer les dépendances requises, exécutez la commande suivante :
npm install
| Développeur d’applications | ### Déployer la pile CloudFormation de routage | Sous-tâche | Description | Compétences requises | | --- | --- | --- | | Lancez le déploiement de la pile de routage. | Pour lancer le déploiement de la pile de CloudFormation routage`CustomDomainRouterStack`, exécutez la commande suivante, en la `example.com` remplaçant par le nom du domaine que vous possédez :
npx cdk deploy CustomDomainRouterStack --parameters PrerequisiteDomainName=example.com
Le déploiement de la pile ne réussira pas tant que la tâche de validation DNS du domaine suivante n'aura pas été exécutée avec succès. | Développeur d’applications | ### Vérifier la propriété du domaine | Sous-tâche | Description | Compétences requises | | --- | --- | --- | | Vérifiez la propriété de votre domaine. | Le certificat restera dans le statut En **attente de validation** jusqu'à ce que vous prouviez que vous êtes propriétaire du domaine associé. Pour prouver que vous en êtes le propriétaire, ajoutez des enregistrements CNAME à la zone hébergée associée au domaine. Pour plus d'informations, consultez la section [Validation DNS](https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html) dans la AWS Certificate Manager documentation. L'ajout des enregistrements appropriés permet au `CustomDomainRouterStack` déploiement de réussir. | Développeur d'applications, administrateur système AWS, administrateur réseau | | Créez un enregistrement d'alias pour pointer vers votre domaine personnalisé API Gateway. | Une fois le certificat émis et validé avec succès, [créez un enregistrement DNS](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-regional-api-custom-domain-create.html#apigateway-regional-api-custom-domain-dns-record) qui pointe vers l'URL de votre domaine personnalisé Amazon API Gateway. L'URL du domaine personnalisé est générée de manière unique par le provisionnement du domaine personnalisé et est spécifiée en tant que paramètre CloudFormation de sortie. Voici un [exemple de record](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-values-basic.html) : **Politique de routage** : routage simple**Nom de l'enregistrement** : `demo.api-gateway-custom-domain-versioning.example.com`**Alias** : Oui**Type d'enregistrement** : enregistrement DNS de type « A » qui pointe vers une AWS ressource**Value (Valeur)** : `d-xxxxxxxxxx.execute-api.xx-xxxx-x.amazonaws.com`**TTL (secondes)** : 300 | Développeur d'applications, administrateur système AWS, administrateur réseau | ### Déployez CloudFormation des piles et appelez l'API | Sous-tâche | Description | Compétences requises | | --- | --- | --- | | Déployez la `ApiStackV1` pile. | Pour déployer la `ApiStackV1` pile, utilisez la commande suivante :
npm run deploy-v1
Le code CDK suivant ajoute un mappage d'API :
var apiMapping = new CfnApiMapping(this, "ApiMapping", {
      apiId: this.lambdaRestApi.restApiId,
      domainName: props.customDomainName.domainName,
      stage: "api",
      apiMappingKey: "api/v1",
    });
| Développeur d’applications | | Déployez la `ApiStackV2` pile. | Pour déployer la `ApiStackV2` pile, utilisez la commande suivante :
npm run deploy-v2
| Développeur d’applications | | Appelez l'API. | Pour appeler l'API et tester les points de terminaison de l'API à l'aide de Bruno, consultez les instructions de la section [Informations supplémentaires](#implement-path-based-api-versioning-by-using-custom-domains-additional). | Développeur d’applications | ### nettoyer des ressources ; | Sous-tâche | Description | Compétences requises | | --- | --- | --- | | nettoyer les ressources. | Pour détruire les ressources associées à cet exemple d'application, utilisez la commande suivante :
npx cdk destroy --all
Assurez-vous de nettoyer tous les enregistrements DNS Route 53 ajoutés manuellement pour le processus de vérification de la propriété du domaine. | Développeur d’applications | ## Résolution des problèmes | Problème | Solution | | --- | --- | | Le déploiement `CustomDomainRouterStack` expire car le certificat ne peut pas être validé. | Assurez-vous d'avoir ajouté les enregistrements CNAME de validation DNS appropriés, comme décrit dans la tâche précédente. Votre nouveau certificat peut continuer à afficher le statut **En attente de validation** jusqu'à 30 minutes après l'ajout des enregistrements de validation DNS. Pour plus d'informations, consultez la section [Validation DNS](https://docs.aws.amazon.com/acm/latest/userguide/dns-validation.html) dans la AWS Certificate Manager documentation. | ## Ressources connexes + [Implémentation du versionnement d'API Gateway basé sur les en-têtes avec Amazon CloudFront](https://aws.amazon.com/blogs/compute/implementing-header-based-api-gateway-versioning-with-amazon-cloudfront/) — Ce billet de AWS Compute Blog propose une stratégie de gestion des versions basée sur les en-têtes comme alternative à la stratégie de version basée sur les chemins décrite dans ce modèle. + [AWS CDK Atelier](https://cdkworkshop.com/20-typescript.html) — Cet atelier d'introduction se concentre sur la création et le déploiement d'applications AWS à l'aide du AWS Cloud Development Kit (AWS CDK). Cet atelier prend en charge Go, Python et TypeScript. ## Informations supplémentaires **Tester votre API avec Bruno** Nous vous recommandons d'utiliser [Bruno](https://www.usebruno.com/), un outil de test d'API open source, pour vérifier que le routage basé sur le chemin fonctionne correctement pour l'exemple d'application. Ce modèle fournit une collecte d'échantillons pour faciliter le test de votre exemple d'API. Pour appeler et tester votre API, procédez comme suit : 1. [Installez Bruno.](https://www.usebruno.com/downloads) 1. Ouvrez Bruno. 1. Dans le [référentiel de code](https://github.com/aws-samples/path-based-versioning-with-api-gateway) de ce modèle, sélectionnez **Bruno/sample-API- Gateway-Custom-Domain-Versioning ** et ouvrez la collection. 1. Pour voir le menu déroulant **Environnements** en haut à droite de l'interface utilisateur (UI), sélectionnez une demande dans la collection. 1. Dans le menu déroulant **Environnements**, sélectionnez **Configurer**. 1. Remplacez la `REPLACE_ME_WITH_YOUR_DOMAIN` valeur par votre domaine personnalisé. 1. Choisissez **Enregistrer**, puis fermez la section **Configuration**. 1. Pour **l'environnement Sandbox**,**** vérifiez que l'option **Active** est sélectionnée. 1. Appelez votre API en utilisant le bouton **->** pour la demande sélectionnée. 1. Prenez note de la façon dont la validation (transmission de valeurs non numériques) est gérée dans V1 par rapport à V2. Pour voir des captures d'écran d'un exemple d'appel d'API et une comparaison des validations V1 et V2, voir **Tester votre exemple d'API** dans le `README.md` fichier du [référentiel de code](https://github.com/aws-samples/path-based-versioning-with-api-gateway) de ce modèle.