Déploiement d’un catalogue Amazon API Gateway pour développeurs/consommateurs d’API

Amazon API Gateway est un service entièrement managé, qui permet aux développeurs de créer, publier, gérer, surveiller et sécuriser facilement des API à n’importe quelle échelle. Les clients de ces APIs ont souvent besoin d’un site web leur permettant de découvrir et d’apprendre à utiliser les APIs disponibles. Ces clients incluent les développeurs front-end, les clients tiers ou les ingénieurs systèmes en interne. Pour mettre un place un tel site, nous avons créé le Catalogue Amazon API Gateway pour développeurs/consommateurs d’API.

Le catalogue d’API basé sur API Gateway (portail développeur ou portail) est une application que vous utilisez pour mettre vos APIs à disposition de vos clients permettant ainsi la découverte en libre service de ces APIs. Vos clients peuvent utiliser le portail développeur pour parcourir la documentation des APIs, s’enregistrer et recevoir immédiatement leur propre clef API nécessaire pour construire des applications, tester les APIs publiées, et surveiller leur utilisation des APIs.

L’équipe du service API Gateway a contribué au projet en open source, le rendant disponible sur Github. Le portail développeur a été publié initialement en Octobre 2018, et l’équipe continue à ajouter des fonctionnalités et à recueillir les retours de la communauté open source. Ce post a pour objectif de rappeler quelques unes des fonctionnalités clefs de ce portail.

Avantages pour les créateurs d’API

Les créateurs d’API utilisent le portail pour exposer les APIs dont ils disposent. En tant que créateur d’API, vous devez mettre en place, maintenir, et activer le portail développeur. Le nouveau portail fournit les avantages suivants:

• Déploiement – Vous pouvez utiliser le modèle d’application serverless AWS (AWS Serverless Application Model or AWS SAM) ou AWS Serverless Application Repository pour déployer votre portail.
• Sécurité – Le portail développeur est sécurisé avec un Groupe d’utilisateurs Amazon Cognito et l’accès peut-être fédéré à partir d’un annuaire sur site ou au travers d’identifiants de réseaux sociaux.
• Personnalisation – Vous pouvez publier le site sous votre propre domaine et ajouter votre propre logo, style, et contenu au portail.

Avantages pour les consommateurs d’API

Les consommateurs d’API utilisent le portail comme une application traditionnelle. Un consommateur d’API doit comprendre les APIs qui sont publiées. Les consommateurs d’API peuvent être des développeurs front-end, des ingénieurs de systèmes distribués, ou des client tiers. Le nouveau portail fournit aux consommateurs d’API les avantages suivants :

• Explorer – Les consommateurs d’API peuvent rapidement parcourir les listes d’APIs. Lorsqu’ils en trouvent une qui les intéresse, ils peuvent immédiatement en lire la documentation.
• Apprendre – Les consommateurs d’API peuvent avoir besoin de creuser plus en avant une API pour en apprendre les détails. Ils veulent comprendre comment construire une requête et quelle réponse ils doivent en attendre.
• Tester – A travers le portail développeur, les consommateurs d’API peuvent obtenir une clef API et invoquer l’API directement. Cela leur permet de développer plus rapidement et avec plus de confiance.

Architecture

Le portail développeur est une application totalement serverless. Il exploite Amazon API Gateway, les Groupes d’utilisateurs Amazon Cognito, AWS Lambda, Amazon DynamoDB, et Amazon S3. Les architectures Serverless vous permettent de construire et d’exécuter des applications sans provisionner, mettre à l’échelle, ni gérer de serveurs. Le portail développeur est divisé en plusieurs Microservices, chacun avec leur responsabilité distincte, comme indiqué dans le schéma ci-dessous :

La gestion des identités pour le portail est effectué par Amazon Cognito et une fonction Lambda au sein du microservice “Login & Registration”. Un groupe d’utilisateur Amazon Cognito est configuré pour permettre aux utilisateurs de s’enregistrer et s’identifier. Vous pouvez de plus utiliser une UI hébergée par Amazon Cognito, personnalisable à votre style et marque.

Les requêtes sont dirigées vers du contenu statique fourni par Amazon S3 et construit avec le framework React. L’application React communique avec le backend fait en Lambda via API Gateway. La fonction Lambda est construite avec la librairie aws-serverless-express et contient la logique métier de l’API. La logique métier de l’application web effectue des requêtes et envoie des données aux microservices “API Key Creation” et “Catalog Update”.

Afin de maintenir le catalogue d’API, le Microservice “Catalog Update” fonctionne grâce à un compartiment S3 et une fonction Lambda. Quand un fichier de définition d’API Swagger est ajouté ou supprimé du compartiment, la fonction Lambda est déclenchée et met à jour le fichier catalog.json à la racine du compartiment S3.
Pour gérer la correspondance entre les clefs d’API et les clients, l’application utilise le microservice “API Key Creation”. Ce dernier met à jour API Gateway lors de la création et de la suppression de clefs API, puis enregistre les résultats dans une table DynamoDB qui fait le lien entre les clients et les clefs API.

Déploiement du portail pour développeur

Vous pouvez déployer le portail pour développeur à l’aide d’AWS SAM soit en utilisant le CLI AWS SAM, ou depuis le AWS Serverless Application Repository. Pour déployer à l’aide d’AWS SAM, vous pouvez simplement cloner le dépôt puis déployer l’application grâce à deux commandes de votre CLI. Pour des instructions détaillées de démarrage avec le portail, voir la page Catalogue Amazon API Gateway pour développeurs/consommateurs d’API dans le Manuel du développeur API Gateway.

Sinon, vous pouvez aussi déployer depuis le AWS Serverless Application Repository comme indiqué ci-après :

1. Naviguez vers la page de l’application api-gateway-dev-portal et cliquez sur Deploy en haut à droite,

2. Sur la page de Review, entrez des noms uniques pour les compartiments ArtifactsS3BucketName et DevPortalSiteS3BucketName. Ceux-ci seront créés pour vous.

3. Pour déployer l’application avec ces paramètres, choisissez Deploy en bas de la page,

4. Une fois la création de la pile complétée, récupérez l’URL du portail en choisissant View CloudFormation Stack. Dans la rubrique Outputs, cliquez sur l’URL dans Value. L’URL doit s’ouvrir dans votre navigateur.

Vous disposez maintenant de votre propre portail de catalogue d’API, déployé et prêt à être utilisé.

Publication d’une nouvelle API

Une fois l’application portail du développeur déployée, vous pouvez publier vos propres API sur le portail.
Pour démarrer:

1. Créez l’API PetStore, disponible comme API d’exemple sur API Gateway. L’API doit être créée, déployée et inclure un stage.
2. Créez un plan d’utilisation, requis pour que les consommateurs de l’API puissent créer des clefs API sur le portail développeur. La clef API est utilisée pour tester les appels API réels.

3. Dans la console API Gateway, naviguez vers la section Stages de votre API

4. Choisissez Export

5. Pour Export as Swagger + API Gateway Extensions, choisissez JSON. Sauvegardez le fichier avec un nom au format suivant: apiId_stageName.json.

6. Téléchargez le fichier obtenu vers le compartiment S3 dédié aux artéfacts dans le chemin “catalog”. Dans ce billet, le compartiment s’appelle apigw-dev-portal-artifacts. Pour le chargement, lancez la commande suivante:

aws s3 cp apiId_stageName.json s3://yourBucketName/catalog/apiId_stageName.json

Le chargement du fichier dans le compartiment des artéfacts avec un préfixe catalog/key le fait automatiquement apparaître sur le portail du développeur.

Vous retrouvez ici la documentation de votre API PetStore affiché dans le format OpenAPI.
Maintenant qu’une API est déployée, vous êtes prêt pour personnaliser l’apparence du portail.

Personnalisation du portail

Ajouter un style propre au votre marque ou identité est simple, et cela permet de créer une expérience utilisateur positive. Vous avez la possibilité de personnaliser le nom de domaine, le texte, le logo et le style. Pour une présentation plus approfondie des composants personnalisables, référez vous à la page Customization du projet Github.

Examinons de plus près quelques possibilités de personnalisation pour rendre votre portail plus agréable pour vos consommateurs d’API.

Personnalisation du logo et des images

Pour personnaliser les logos, images ou contenus, vous devez modifier le contenu du compartiment S3 your-prefix-portal-static-assets. Vous pouvez modifier les fichiers à l’aide du CLI ou de la console AWS.

Commencez à personnaliser le portail en téléchargeant un nouveau logo pour la barre de navigation:
1. Téléchargez le nouveau logo dans votre compartiment avec une clef nommée custom-content/nav-logo.png.

aws s3 cp {myLogo}.png s3://your-prefix-portal-static-assets/custom-content/nav-logo.png

2. Modifiez les droits d’accès à l’objet pour que le fichier soit lisible par tous puisque c’est une image publique. La nouvelle barre de navigation a alors cette apparence par exemple :

Une autre personnalisation peut être d’ajouter une image spécifique à une API et un stage. Par exemple, vous voulez que votre API PetStore affiche une image de chien pour figurer la convivialité de votre API. Pour ajouter l’image :

1. Utilisez la ligne de commande pour copier l’image directement vers S3 :

aws s3 cp my-image.png s3://your-prefix-portal-static-assets/custom-content/api-logos/apiId-stageName.png

2. Modifiez les droits d’accès à l’objet pour le rendre lisible par tous.

Personnalisation du texte

Ensuite, assurez-vous que le texte de votre portail souhaite la bienvenue à votre clientèle d’amoureux des animaux. Les fichiers YAML situés sous /custom-content/content-fragments/ dans le compartiment du contenu statique contiennent les textes du portail.
Pour éditer ces textes :

1. Dans la console AWS, naviguez vers le compartiment S3 du contenu du site web, et vers le préfixe /custom-content/content-fragments/

2. Home.md est le contenu affiché sur la page d’accueil, APIs.md contrôle l’onglet APIs, et GettingStarted.md contient le texte de l’onglet Getting Started. Ces trois fichiers sont écrits en markdown. Téléchargez l’un d’eux en local pour en éditer le contenu. Voici par exemple Home.md modifié pour en personnaliser le texte :

3. Une fois le fichier modifié et sauvegardé, chargez le à nouveau vers S3, ce qui personnalisera la page d’accueil. Voici le résultat obtenu avec les modifications de l’étape précédente:

Personnalisation du nom de domaine

Pour finir, de nombreux clients souhaitent utiliser pour leur portail un nom de domaine qu’ils possèdent et contrôlent. Pour personnaliser le nom de domaine :

1. Demandez et validez un certificat managé pour votre nom de domaine personnalisé avec AWS Certificate Manager. Pour plus d’informations, référez-vous à la page Demander un certificat public du Guide de l’utilisateur d’AWS Certificate Manager.

2. Copiez l’Amazon Resource Name (ARN) afin de pouvoir l’utiliser lors du processus de déploiement du portail. Ce processus inclut maintenant l’ARN du certificat et une propriété appelée UseRoute53Nameservers. Si cette propriété est mise à true, le template crée une zone hébergée (hosted zone) et un enregistrement (record set) pour vous sur Amazon Route 53. Si la propriété est mise à false, le template s’attend à ce que vous utilisiez votre propre hébergement de nom de serveur.

3. Si vous avez déployé depuis l’AWS Serverless Application Repository, naviguez vers la page de l’Application et modifiez les paramètres de l’application pour déployer en utilisant l’ARN du certificat.

Une fois le portail déployé et l’enregistrement CNAME ajouté, le site web est accessible depuis votre nom de domaine personnalisé ainsi que depuis la nouvelle URL Amazon CloudFront.

La personnalisation du logo, du contenu textuel et du nom de domaine sont parfaits pour que votre portail apparaisse comme une application développée en interne. A travers cette présentation, vous avez pu déployer et modifier complètement l’apparence du portail pour permettre aux développeurs et consommateurs d’API de découvrir et naviguer dans ces APIs avec votre identité visuelle.

Conclusion

Le catalogue/portail est disponible pour une utilisation immédiate. Son support et les améliorations des fonctionnalités sont suivis dans le dépôt GitHub public. Vous pouvez contribuer au projet en suivant les guides du Code de conduite et de Contribution. Ce projet est open-source sous Amazon Open Source Code of Conduct. Nous prévoyons de continuer à ajouter des fonctionnalités et à prendre en considération les retours clients. Nous sommes impatients de voir ce que les clients vont construire avec API Gateway et le catalogue/portail de présentation des API.

Ecrit par Drew Dresser, Application Architect – AWS Professional Services et traduit en Français par Olivier Chappe, Architecte Solutions AWS Game Tech, LinkedIn.