Utiliser le portail pour développeurs sans serveur pour cataloguer vos API API Gateway - Amazon API Gateway

Utiliser le portail pour développeurs sans serveur pour cataloguer vos API API Gateway

Un portail pour développeurs est une application que vous utilisez pour mettre vos API à la disposition de vos clients. Vous pouvez utiliser le portail pour développeurs sans serveur pour publier les API gérées par API Gateway directement à partir d'API Gateway. Vous pouvez également l'utiliser pour publier des API qui ne sont pas gérées par API Gateway en chargeant les définitions OpenAPI correspondantes. Lorsque vous publiez les API dans un portail pour développeurs, vos clients peuvent facilement réaliser les opérations suivantes :

  • Déterminer quelles API sont disponibles

  • Parcourir la documentation sur les API

  • S'inscrire à leur propre clé d'API —qu'ils reçoivent immédiatement— et qui est nécessaire pour créer des applications

  • Tester vos API dans l'interface utilisateur du portail pour développeurs

  • Surveiller leur propre utilisation des API

Amazon API Gateway publie un portail pour développeurs sans serveur régulièrement mis à jour dans le AWS Serverless Application Repository et sur GitHub. Il est disponible sous la licence Apache 2.0, qui vous permet de le personnaliser et de l'intégrer à vos outils de génération et de déploiement. Le serveur frontal est écrit en React et est conçu pour être entièrement personnalisable. Consultez https://github.com/awslabs/aws-api-gateway-developer-portal/wiki/Customization.

Pour plus d'informations sur le AWS Serverless Application Repository, consultez le Manuel du développeur AWS Serverless Application Repository.

Astuce

Si vous souhaitez tester un exemple de portail pour développeurs, veuillez consulter https://developer.exampleapigateway.com/ portail des développeurs sans serveur.

Créer un portail pour développeurs

Vous pouvez déployer le portail pour développeurs sans serveur API Gateway en l'état ou le personnaliser à votre marque. Vous pouvez déployer votre portail pour développeurs de deux façons :

  • En utilisant AWS Serverless Application Repository. Cliquez sur le bouton Déployer pour lancer la pile AWS CloudFormation du portail pour développeurs sans serveur API Gateway, puis saisissez quelques-uns des paramètres de la pile dans la console Lambda.

  • En téléchargeant le portail pour développeurs sans serveur API Gateway depuis le référentiel AWS GitHub, puis en lançant la pile AWS CloudFormation du portail pour développeurs sans serveur API Gateway à partir de l'interface de ligne de commande AWS SAM.

Pour déployer le portail pour développeurs sans serveur à l'aide du AWS Serverless Application Repository

  1. Accédez à la page du portail pour développeurs sans serveur API Gateway dans le AWS Serverless Application Repository.

  2. Choisissez Deploy (Déployer).

    Note

    Il est possible que vous soyez invité à vous connecter à la console AWS Lambda.

  3. Dans la console Lambda, sous Paramètres d'application, saisissez les paramètres de la pile du portail pour développeurs requis.

    Note

    Les noms de compartiment S3 et le préfixe de domaine Amazon Cognito sont requis ; les autres paramètres sont facultatifs.

  4. Si vous souhaitez activer le bouton de commentaires des clients Got an opinion? (Vous avez un avis ?), vous devez procéder comme suit :

    • Dans la zone DevPortalAdminEmail, entrez l'adresse e-mail. Si un client envoie des commentaires, un e-mail est envoyé à cette adresse.

      Note

      Si vous n'indiquez aucune adresse e-mail, le bouton Got an opinion? (Vous avez un avis ?) n'est pas visible dans le portail pour développeurs.

    • Si vous le souhaitez, entrez un nom de table dans la zone DevPortalFeedbackTableName. Le nom par défaut est DevPortalFeedback. Si un client envoie des commentaires, ceux-ci sont stockés dans une table DynamoDB de ce nom.

  5. Cochez la case en regard de I acknowledge that this app creates custom IAM roles and resource policies (Je reconnais que cette application crée des stratégies de ressources et rôles IAM personnalisés).

  6. Choisissez Deploy (Déployer).

  7. Si vous avez saisi une adresse e-mail dans le paramètre de pile AdminEmail un e-mail d'abonnement Amazon SNS est envoyé à cette adresse e-mail. Cet e-mail confirme votre abonnement à la rubrique Amazon SNS que vous avez spécifiée dans le paramètre MarketplaceSubscriptionTopicProductCode .

Pour télécharger et déployer le portail pour développeurs sans serveur à l'aide d'AWS SAM

  1. Assurez-vous que vous avez installé et configuré les dernières AWS CLI et CLI AWS SAM.

  2. Téléchargez ou clonez le référentiel du portail pour développeurs sans serveur API Gateway .

  3. Assurez-vous que vous disposez d'un compartiment Amazon S3 privé dans lequel vous pouvez charger les fonctions Lambda zippées. Si vous n'en avez pas, vous pouvez en créer un au moyen de l'interface de ligne de commande CLI ou de la console Amazon S3.

    Dans l'interface de ligne de commande AWS SAM, exécutez la commande suivante à partir de la racine du projet, en remplaçant {your-lambda-artifacts-bucket-name} par le nom de votre compartiment Amazon S3 :

    sam package --template-file ./cloudformation/template.yaml \ --output-template-file ./cloudformation/packaged.yaml \ --s3-bucket {your-lambda-artifacts-bucket-name}
  4. Pour cette étape, consultez Paramètres du portail pour développeurs pour plus d'informations sur les paramètres (par exemple CognitoDomainNameOrPrefix) qui suivent --parameter-overrides.

    Note

    Assurez-vous que vous disposez d'un compartiment Amazon S3 privé dans lequel charger le modèle AWS SAM. (AWS CloudFormation lit le modèle à partir du compartiment afin de déployer le portail pour développeurs.) Il peut s'agir du même compartiment que celui que vous avez spécifié à l'étape précédente pour charger les fonctions Lambda compressées.

    À partir de la racine du projet, exécutez la commande suivante en remplaçant :

    • {your-template-bucket-name} par le nom de votre compartiment Amazon S3.

    • {custom-prefix} par un préfixe globalement unique.

    • {cognito-domain-or-prefix} par une chaîne unique.

    sam deploy --template-file ./cloudformation/packaged.yaml \ --s3-bucket {your-template-bucket-name} \ --stack-name "{custom-prefix}-dev-portal" \ --capabilities CAPABILITY_NAMED_IAM \ --parameter-overrides CognitoDomainNameOrPrefix= "{cognito-domain-or-prefix}" DevPortalSiteS3BucketName="{custom-prefix}-dev-portal-static-assets" ArtifactsS3BucketName="{custom-prefix}-dev-portal-artifacts"

Une fois votre portail pour développeurs entièrement déployé, vous pouvez obtenir son URL comme suit.

Pour obtenir l'URL de votre portail pour développeurs nouvellement créé

  1. Ouvrez la console AWS CloudFormation.

  2. Choisissez le nom de la pile (aws-serverless-repository-api-gateway-dev-portal est le nom de la pile par défaut).

  3. Ouvrez la section Outputs. L'URL du portail pour développeurs est spécifiée dans la propriété WebsiteURL.

Paramètres du portail pour développeurs

Vous devez définir les paramètres ci-après pendant et après le déploiement de votre portail pour développeurs :

Note

Vous pourrez modifier la plupart des paramètres ci-dessous après avoir déployé votre portail pour développeurs, en mettant à jour la pile AWS CloudFormation. Pour plus d'informations, consultez Mises à jour des piles AWS CloudFormation.

ArtifactsS3BucketName (REQUIS)

Le processus de déploiement crée un compartiment Amazon S3 accessible en privé dans lequel les métadonnées du catalogue seront stockées. Spécifiez un nom à attribuer au compartiment. Ce nom doit être unique au niveau mondial.

CognitoDomainNameOrPrefix (REQUIS)

Cette chaîne est utilisée avec l'interface utilisateur hébergée par Amazon Cognito pour l'inscription et la connexion d'utilisateurs. Spécifiez un nom de domaine ou une chaîne de préfixe unique.

CognitoIdentityPoolName

Le processus de déploiement crée un pool d'identités Amazon Cognito. Le nom par défaut du groupe d'identités est nommé DevPortalIdentityPool.

CustomDomainNameAcmCertArn

Si vous avez indiqué un nom de domaine associé à un certificat ACM, vous devez également spécifier ici l'ARN du certificat ACM. Laissez ce champ vide afin de créer un portail pour développeurs sans nom de domaine personnalisé.

DevPortalAdminEmail

Spécifiez une adresse e-mail pour activer le bouton de commentaires des clients Got an opinion? (Vous avez un avis ?). Si un client envoie des commentaires, un e-mail est envoyé à cette adresse.

Note

Si vous n'indiquez aucune adresse e-mail, le bouton Got an opinion? (Vous avez un avis ?) n'est pas visible dans le portail pour développeurs.

DevPortalFeedbackTableName

Si vous spécifiez une adresse e-mail pour DevPortalAdminEmail, le processus de déploiement crée une table DynamoDB où stocker les commentaires saisis par les clients. Le nom par défaut est DevPortalFeedback. Si vous le souhaitez, vous pouvez spécifier votre propre nom de table.

DevPortalCustomersTableName

Le processus de déploiement crée une DynamoDB table dans laquelle les comptes clients sont stockés. Si vous le souhaitez, vous pouvez nommer cette table. Ce nom doit être unique au sein de la région de votre compte. Par défaut, la table est nommée DevPortalCustomers.

DevPortalSiteS3BucketName (REQUIS)

Le processus de déploiement crée un compartiment Amazon S3 accessible en privé dans lequel le code de l'application web est stocké. Spécifiez un nom à attribuer à ce compartiment. Ce nom doit être unique au niveau mondial.

MarketplaceSubscriptionTopicProductCode

Il s'agit du suffixe de la rubrique Amazon SNS pour les événements d'abonnement/de désabonnement. Entrez la valeur souhaitée. La valeur par défaut est DevPortalMarketplaceSubscriptionTopic. Ce paramètre s'applique uniquement si vous utilisez l'intégration AWS Marketplace. Pour plus d'informations, consultez Configuration de votre produit SaaS afin qu'il accepte de nouveaux clients.

StaticAssetRebuildMode

Par défaut, la regénération d'une ressource statique ne remplace pas le contenu personnalisé. Spécifiez overwrite-content pour remplacer le contenu personnalisé par votre version locale.

Important

Si vous spécifiez overwrite-content, toutes les modifications personnalisées dans votre compartiment Amazon S3 seront perdues. N'agissez ainsi que si vous êtes sûr de ce que vous faites.

StaticAssetRebuildToken

Fournissez un jeton différent de celui du dernier déploiement pour recharger les ressources statiques du site du portail pour développeurs. Vous pouvez fournir un horodatage ou un GUID sur chaque déploiement afin de toujours recharger les ressources.

UseRoute53Nameservers

S'applique uniquement si vous créez un nom de domaine personnalisé pour votre portail pour développeurs. Spécifiez true afin d'ignorer la création d'une zone hébergée et d'un jeu d'enregistrements Route 53. Vous devez fournir votre propre hébergement de serveurs de noms à la place de Route 53. Sinon, laissez ce champ défini sur false.

Création d'un utilisateur administrateur pour votre portail pour développeurs

Après avoir déployé votre portail pour développeurs, créez au moins un utilisateur administrateur. Pour ce faire, créez un utilisateur et ajoutez-le au groupe d'administrateurs du groupe d'utilisateurs d'Amazon Cognito créé par AWS CloudFormation lorsque vous avez déployé le portail pour développeurs.

Créer un utilisateur administrateur

  1. Dans le portail pour développeurs, choisissez Register (S'inscrire).

  2. Entrez une adresse e-mail et un mot de passe et choisissez Registrer (S'inscrire).

  3. Dans un autre onglet du navigateur, connectez-vous à la console Amazon Cognito.

  4. Sélectionnez Manage User Pools (Gérer les groupes d'utilisateurs).

  5. Choisissez le groupe d'utilisateurs pour le portail pour développeurs que vous avez défini lorsque vous avez déployé le portail.

  6. Choisissez l'utilisateur à promouvoir en administrateur.

  7. Choisissez Ajouter au groupe.

  8. Dans le menu déroulant, choisissez {nompile}-dev-portalAdminsGroup, où {nompile} est le nom de la pile lorsque vous avez déployé le portail pour développeurs.

  9. Choisissez Ajouter au groupe.

  10. Dans le portail pour développeurs, déconnectez-vous puis reconnectez-vous à l'aide des mêmes informations d'identification. Un lien Admin Panel (Panneau d'administration) doit maintenant apparaître dans le coin supérieur droit, en regard de My Dashboard (Mon tableau de bord).

Gérer les utilisateurs pour votre portail pour développeurs

Après vous être connecté en tant qu'utilisateur administrateur, vous pouvez utiliser la section Comptes du Panneau d'administration pour gérer les utilisateurs. Un utilisateur administrateur peut inviter de nouveaux utilisateurs, supprimer des utilisateurs et promouvoir les utilisateurs existants au statut d'administrateur à partir du portail des développeurs.

Publication d'une API gérée par API Gateway sur votre portail pour développeurs

Les étapes ci-après décrivent comment vous, en tant que propriétaire de l'API, publiez une API sur votre portail pour développeurs afin que vos clients puissent s'y s'abonner.

Étape 1 : Rendre une API gérée par API Gateway disponible pour la publication

  1. Si vous le n'avez pas déjà fait, déployez l'API jusqu'à une étape.

  2. Si vous ne l'avez pas déjà fait, créez un plan d'utilisation et associez-le à l'étape de l'API déployée.

    Note

    Il n'est pas nécessaire d'associer les clés d'API au plan d'utilisation. Le portail développeur le fait pour vous.

  3. Connectez-vous au portail pour développeurs et accédez au panneau d'administration.

  4. L'API doit maintenant apparaître dans la liste des API du panneau d'administration. Dans la liste des API, celles-ci sont regroupées par plan d'utilisation. Le groupe Not Subscribable No Usage Plan répertorie les API qui ne sont pas associées à un plan d'utilisation.

Étape 2 : Rendre l'API gérée par API Gateway visible dans le portail pour développeurs

  1. Dans la liste des API du panneau d'administration, vérifiez la valeur affichée pour votre API. Quand elle est chargée pour la première fois, cette valeur est définie sur False (Faux).

  2. Pour rendre l'API visible dans le portail pour développeurs, sélectionnez le bouton False (Faux). Sa valeur passe à True, ce qui indique que l'API est maintenant visible.

    Astuce

    Pour rendre toutes les API visibles dans un plan d'utilisation, choisissez le bouton False (Faux) ou Partial (Partiel) dans la barre d'en-tête du plan d'utilisation.

  3. Accédez au panneau des API afin de voir le portail pour développeurs tel que vos clients le voient. Votre API doit être répertoriée dans la colonne de navigation de gauche.

    Si l'API est déployée à une étape associée à un plan d'utilisation, un bouton Subscribe (S'abonner) est visible pour l'API. Ce bouton permet d'associer la clé d'API du client au plan d'utilisation auquel l'API est associée.

Maintenant que l'API gérée par API Gateway est affichée, vous pouvez activer la génération du kit SDK afin que vos clients puissent télécharger un kit SDK correspondant.

Étape 3 : Activer la génération du kit SDK

  1. Dans la liste des API du panneau d'administration, choisissez le bouton Disabled (Désactivé). Sa valeur passe à Enabled (Activé), ce qui indique que la génération du SDK est désormais autorisée.

  2. Accédez au panneau des API et choisissez votre API dans la colonne de navigation de gauche. Vous devriez maintenant voir les boutons Télécharger le kit SDK et API d’exportation .

Mise à jour ou suppression d'une API gérée par API Gateway

Si vous apportez des modifications à votre API dans API Gateway après l'avoir publiée, vous devez la redéployer.

Pour mettre à jour une API gérée par API Gateway

  1. Apportez les modifications souhaitées à l'API dans la console API Gateway, l'AWS CLI ou un kit SDK.

  2. Redéployez l'API à la même étape qu'auparavant.

  3. Dans le portail pour développeurs, dans la liste des API du panneau d'administration, choisissez Update (Mettre à jour). Cela met à jour l'API affichée dans l'interface utilisateur du portail pour développeurs.

    Note

    Le bouton Download SDK (Télécharger le kit SDK) récupère toujours la dernière version déployée de l'API, même si vous ne l'avez pas mise à jour dans le portail pour développeurs.

  4. Accédez au panneau des API et choisissez votre API dans la colonne de navigation de gauche. Vos modifications sont normalement visibles.

Pour arrêter l'affichage d'une API dans la liste des API du portail pour développeurs (sans révoquer l'accès des clients à celui-ci) :

  1. Dans la liste des API du panneau d'administration, vérifiez la valeur affichée pour votre API. Si l'API est visible, cette valeur est définie sur True (Vrai).

  2. Pour rendre l'API invisible, choisissez le bouton True (Vrai). Sa valeur passe à False (Faux), ce qui indique que l'API est désormais invisible.

  3. Accédez au panneau API. Votre API ne doit plus être répertoriée dans la colonne de navigation de gauche.

Pour révoquer l'accès des clients à une API sans supprimer entièrement celle-ci, procédez de l'une des manières suivantes dans la console API Gateway, l'interface de ligne de commande API Gateway ou l'API REST :

  • Supprimez les clés d'API du plan d'utilisation.

  • Supprimez l'étape de l'API du plan d'utilisation.

Supprimer une API non gérée par API Gateway

Pour arrêter l'affichage d'une API non gérée par API Gateway et supprimer l'accès des clients à cette API, choisissez Delete (Supprimer). Cela ne supprime pas l'API, mais supprime son fichier de spécification OpenAPI du portail pour développeurs.

Publication d'une API non gérée par API Gateway sur votre portail pour développeurs

Les étapes suivantes décrivent comment publier des API non gérées par API Gateway (ou « génériques ») pour vos clients. Vous pouvez charger les définitions OpenAPI 2.0 (Swagger) ou 3.x des API dans les fichiers JSON, YAML ou YML.

Pour publier une API non gérée par API Gateway dans votre portail pour développeurs

  1. Connectez-vous au portail pour développeurs et accédez au panneau d'administration.

  2. Sous Generic APIs (API génériques), choisissez Add API (Ajouter une API).

  3. Accédez au répertoire où résident les fichiers OpenAPI de vos API et choisissez les fichiers à charger.

  4. Choisissez Upload.

    Note

    Si l'un des fichiers ne peut pas être analysé ou ne contient pas de titre d'API, un avertissement s'affiche et ces fichiers ne seront pas chargés. Tous les autres fichiers sont chargés. Pour ignorer la boîte de dialogue, choisissez l'icône x.

  5. Votre API doit maintenant être répertoriée sous Generic APIs (API génériques). Sinon, quittez le panneau d'administration, puis revenez-y pour actualiser la liste.

Comment vos clients utilisent votre portail pour développeurs

Pour créer des applications et tester vos API, vos clients doivent créer plusieurs comptes développeur en s'inscrivant sur votre portail pour développeurs.

Pour créer un compte développeur et obtenir une clé d'API

  1. Dans le portail pour développeurs, choisissez Register (S'inscrire).

  2. Entrez une adresse e-mail et un mot de passe et choisissez Registrer (S'inscrire).

  3. Pour localiser la clé d'API, choisissez My Dashboard (Mon tableau de bord).

Un compte développeur donne à votre client une clé API, qui est généralement nécessaire pour utiliser et tester vos API. Il permet le suivi de l'utilisation pour vous et vos clients.

Lorsqu'un client s'inscrit pour la première fois, sa nouvelle clé d'API ne sera liée à aucune de vos API.

Pour activer la clé d'API d'une API

  1. Choisissez APIs.

  2. Choisissez l'API dans la liste d'API et choisissez Subscribe (S'abonner).

    Ceci permet d'associer la clé d'API au plan d'utilisation auquel l'API est associée.

Le client est désormais abonné à l'API et peut effectuer des appels aux méthodes de l'API. Les statistiques d'utilisation quotidienne de l'API s'afficheront dans MyDashboard.

Un client peut tester les méthodes d'API dans l'interface utilisateur du portail pour développeurs sans s'abonner.

Note

Si l'une des méthodes d'API nécessite une clé d'API, un bouton Authorize (Autoriser) s'affiche au-dessus de la liste des méthodes. Les méthodes qui nécessitent une clé d'API sont désignées par une icône de cadenas noir. Pour tester les méthodes qui nécessitent une clé d'API, choisissez le bouton Authorize (Autoriser) et entrez une clé d'API valide qui est associée au plan d'utilisation pour l'étape de l'API.

Vous pouvez ignorer le bouton Authorize (Autoriser) lorsqu'il s'affiche sur les API auxquelles vous êtes déjà abonné.

Vos clients peuvent envoyer leurs commentaires via le portail des développeurs.

Les commentaires du client sont stockés dans la table DynamoDB du portail pour développeurs. Par défaut, cette table est nommée DevPortalFeedback. En outre, un e-mail est envoyé aux adresses e-mail spécifiées dans le champ DevPortalAdminEmail. Si aucune adresse e-mail n'a été spécifiée lors du déploiement du portail pour développeurs, le bouton Vous avez un avis ? n'est pas visible.

Note

Si vous modifiez le nom de cette table, utilisez un nom qui est unique au sein de la région de votre compte.

Si vous avez activé la génération du kit SDK pour l'API dans le Panneau d'administration, le client peut télécharger un kit SDK pour celle-ci et exporter la définition de l’API. Pour en savoir plus, consultez Génération d'un kit SDK pour une API REST dans API Gateway et Exportation d'une API REST depuis API Gateway.

Bonnes pratiques relatives aux portails pour développeurs

Voici quelques suggestions de bonnes pratiques à suivre lors du déploiement d'un portail pour développeurs.

  • Dans la plupart des cas, il suffit de déployer un portail pour développeurs pour l'ensemble de vos API. Dans certains cas, vous pouvez préférer avoir des portails pour développeurs distincts pour les versions de développement et de production de vos API. Nous ne recommandons pas d'utiliser plus d'un portail de développement pour les API de production.

  • Lorsque vous créez un plan d'utilisation et l'associez à une étape, vous n'avez pas besoin d'associer des clés d'API au plan d'utilisation. Le portail développeur le fait pour vous.

  • Notez que toutes les API dans un plan d'utilisation donné peuvent faire l'objet d'un abonnement, même si vous ne les avez pas rendues visibles pour vos clients.