Tutoriel : Création d'une API REST par l'importation d'un exemple - Amazon API Gateway

Tutoriel : Création d'une API REST par l'importation d'un exemple

Vous pouvez utiliser la console Amazon API Gateway pour créer et tester une API REST simple avec l'intégration HTTP pour un site web PetStore. La définition d'API est préconfigurée comme fichier OpenAPI 2.0. Après le chargement de la définition d'API dans API Gateway, vous pouvez utiliser la console API Gateway pour examiner la structure de base de l'API ou simplement déployer et tester l'API.

L'exemple d’API PetStore prend en charge les méthodes suivantes pour permettre à un client d’accéder au site Web du serveur principal HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • GET / : pour l'accès en lecture de la ressource racine de l'API qui n'est pas intégrée à un point de terminaison du serveur principal. API Gateway répond avec une présentation du site web PetStore. Il s'agit d'un exemple du type d'intégration MOCK.

  • GET /pets : pour l'accès en lecture de la ressource /pets de l'API intégrée à la ressource /pets du serveur principal de même nom. Le serveur principal renvoie la page des animaux domestiques disponibles sur le site web PetStore. Il s'agit d'un exemple du type d'intégration HTTP. L'URL du point de terminaison de l'intégration est http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • POST /pets : pour l'accès en écriture de la ressource /pets de l'API intégrée à la ressource /petstore/pets du serveur principal. Après avoir reçu une demande correcte, le backend ajoute l'animal spécifié au PetStore et renvoie le résultat au mandataire. Il s'agit aussi d'une intégration HTTP.

  • GET /pets/{petId} : pour l'accès en lecture à un animal identifié par une valeur petId telle que spécifiée comme variable du chemin d'accès de l'URL de la demande entrante. Cette méthode possède également le type d'intégration HTTP. Le serveur principal renvoie l'animal spécifié trouvé sur le site PetStore. L'URL du point de terminaison HTTP du serveur principal est http://petstore-demo-endpoint.execute-api.com/petstore/pets/n, où n désigne un nombre entier comme identifiant de l'animal recherché.

L'API prend en charge l'accès CORS via les méthodes OPTIONS du type d'intégration MOCK. API Gateway renvoie les en-têtes requis prenant en charge l'accès CORS.

La procédure suivante vous guide à travers les étapes de création et de test d'une API à partir d'un exemple à l'aide de la console API Gateway.

Pour importer, créer et tester l'exemple d'API

  1. Si vous ne l'avez pas déjà fait, suivez les étapes de Conditions préalables : Préparation à la création d'une API dans API Gateway.

  2. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

  3. Si vous utilisez API Gateway pour la première fois, vous voyez une page qui vous présente les fonctions du service. Sous REST API (API REST), choisissez Build (Création). Lorsque la fenêtre contextuelle Create Example API (Créer API exemple) s'affiche, cliquez sur OK.

    Si ce n'est pas la première fois que vous utilisez API Gateway, choisissez Create API (Créer une API). Sous REST API (API REST), choisissez Build (Création).

  4. Sous Create new API (Créer une nouvelle API), sélectionnez Examples API (Exemples d'API), puis Import (Importer) pour créer l'exemple d'API. Pour votre première API, la console API Gateway commence avec cette option par défaut.

    Vous pouvez faire défiler la définition OpenAPI vers le bas pour voir les détails de cet exemple d'API avant de sélectionne Import (Importer).

  5. L'API nouvellement créée est affichée comme suit :

    Le volet Resources illustre la structure de l'API créée sous la forme d'une arborescence de nœuds. Les méthodes d'API définies sur chaque ressource sont les arêtes de l'arborescence. Lorsqu'une ressource est sélectionnée, toutes ses méthodes sont répertoriées dans le volet Methods de droite. Sous chaque méthode est affiché un bref récapitulatif de la méthode, notamment l'URL de son point de terminaison, son type d'autorisation et l'exigence d'une clé API.

  6. Pour afficher les détails d'une méthode, modifier sa configuration ou tester l'appel de cette méthode, sélectionnez le nom de la méthode dans la liste des méthodes ou dans l'arborescence des ressources. Ici, nous avons choisi la méthode POST /pets comme illustration :

    Le volet Method Execution obtenu présente une vue logique de la structure et des comportements de la méthode (POST /pets) choisie : Method Request et Method Response sont les API d'interface avec le serveur frontal de l'API (un client), tandis que Integration Request et Integration Response sont les API d'interface avec le backend (http://petstore-demo-endpoint.execute-api.com/petstore/pets). Un client utilise l'API pour accéder à une fonction backend via Method Request (Demande de méthode). Si nécessaire, API Gateway convertit la demande du client au format acceptable pour le backend dans Integration Request (Demande d'intégration) avant de la transférer vers ce backend. La demande transformée est connue en tant que demande d'intégration. De même, le backend renvoie la réponse à API Gateway dans Integration Response (Réponse d'intégration). Ensuite, API Gateway l'achemine vers Method Response (Réponse de méthode) avant de l'envoyer au client. Là encore, si nécessaire, API Gateway peut mapper les données de réponse du backend au format attendu par le client.

    Pour la méthode POST sur une ressource d'API, la charge utile de la demande de méthode peut être transmise via la demande d'intégration sans modification, si la charge utile de la demande de méthode est au même format que charge utile de la demande d'intégration.

    La demande de méthode GET / utilise le type d'intégration MOCK et n'est liée à aucun point de terminaison du serveur principal réel. La réponse Integration Response correspondante est configurée pour renvoyer une page HTML statique. Lorsque la méthode est appelée, API Gateway accepte simplement la demande et renvoie immédiatement la réponse d'intégration configurée au client via Method Response (Réponse de méthode). Vous pouvez utiliser l'intégration fictive pour tester une API sans avoir besoin d'un point de terminaison sur le serveur principal. Vous pouvez également l'utiliser pour servir une réponse locale, générée à partir d'un modèle de mappage de corps de réponse.

    En tant que développeur d'API, vous contrôlez les comportements des interactions frontales de votre API en configurant la demande de méthode et une réponse de méthode. Vous contrôlez les comportements des interactions principales de votre API en configurant la demande d'intégration et la réponse d'intégration. Cela implique des mappages de données entre une méthode et l'intégration correspondante. Nous traitons la configuration de la méthode dans Tutoriel : Création d'une API REST avec une intégration HTTP autre que de proxy. Pour l'instant, nous nous concentrons sur le test de l'API pour fournir une expérience utilisateur de bout en bout.

  7. Sélectionnez l'option Test affichée sur Client (comme illustré dans l'image précédente) pour commencer le test. Par exemple, pour tester la méthode POST /pets, saisissez la charge utile {"type": "dog","price": 249.99} suivante dans Request Body avant de choisir le bouton Test.

    Les données d'entrée spécifient les attributs de l'animal que nous voulons ajouter à la liste des animaux sur le site web PetStore.

  8. Les résultats s'affichent comme suit :

    L'entrée Logs de la sortie indique les changements d'état entre la demande de la méthode et la demande d'intégration, et entre la réponse d'intégration et la réponse de la méthode. Cela peut être utile pour résoudre les éventuelles erreurs de mappage susceptibles d'entraîner l'échec de la demande. Dans cet exemple, aucun mappage n'est appliqué : la charge utile de la demande de méthode charge est transmise via la demande d'intégration au serveur principal et, de même la réponse du serveur principal est transmise via la réponse d'intégration à la réponse de la méthode.

    Pour tester l'API à l'aide d'un autre client que la fonction de test de demande d'appel API Gateway, vous devez tout d'abord déployer l'API jusqu'à une étape.

  9. Pour déployer l'exemple d'API, sélectionnez-l'API PetStore, puis choisissez Deploy API dans le menu déroulant Actions.

    Dans le volet Deploy API, sélectionnez [New Stage] dans le champ Deployment stage puisqu'il s'agit du premier déploiement de l'API. Saisissez un nom (par exemple, test) dans le champ Stage name (Nom de l'étape) et saisissez éventuellement des descriptions dans les champs Stage description (Description de l'étape) et Deployment description (Description du déploiement). Choisissez Deploy (Déployer).

    Dans le volet Stage Editor qui s'affiche, Invoke URL affiche l'URL permettant d'appeler la demande de méthode GET / de l'API.

  10. Dans le volet Stage Editor, suivez le lien Invoke URL pour envoyer la demande de méthode GET / dans un navigateur. Une réponse positive renvoie le résultat, généré à partir du modèle de mappage dans la réponse d'intégration.

  11. Dans le volet de navigation Stages (Étapes), développez l'étape test, sélectionnez GET sur /pets/{petId}, puis copiez la valeur du champ Invoke URL (Appeler une URL) de https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}. {petId} représente une variable path.

    Collez la valeur du champ Invoke URL (obtenue à l'étape précédente) dans la barre d'adresse d'un navigateur, en remplaçant {petId} par 1, par exemple, puis appuyez sur Entrée pour envoyer la demande. Une réponse 200 OK doit être renvoyée avec la charge utile JSON suivante :

    { "id": 1, "type": "dog", "price": 249.99 }

    L'appel de la méthode d'API de cette façon est possible, car le type d'autorisation défini dans le champ Authorization est NONE. Si l'autorisation AWS_IAM était utilisée, vous devriez signer la demande à l'aide des protocoles Signature Version 4 (SigV4). Pour voir un exemple de ce type de demande, consultez Tutoriel : Création d'une API REST avec une intégration HTTP autre que de proxy.