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

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.

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 intégration HTTP pour un PetStore site Web. 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' PetStore exemple d'API prend en charge les méthodes suivantes permettant à un client d'accéder au site Web principal HTTP dehttp://petstore-demo-endpoint.execute-api.com/petstore/pets.

Note

Ce didacticiel utilise un point de terminaison HTTP comme exemple. Lorsque vous créez vos propres API, nous vous recommandons d'utiliser des points de terminaison HTTPS pour vos intégrations HTTP.

  • 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 par un aperçu du PetStore site Web. 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 backend renvoie une page des animaux de compagnie disponibles dans le 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. Dès réception d'une demande correcte, le backend ajoute l'animal spécifié au PetStore et renvoie le résultat à l'appelant. 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 backend renvoie l'animal de compagnie spécifié trouvé dans le 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. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

  2. Effectuez l’une des actions suivantes :

    • Pour créer votre première API, pour API REST, choisissez Création.

    • Si vous avez déjà créé une API, choisissez Créer une API, puis Création pour API REST.

  3. Sous Créer une API REST, choisissez Exemple d'API, puis Créer une API pour créer l'exemple d'API.

    Exemple d'API REST dans la console API Gateway.

    Vous pouvez faire défiler la définition OpenAPI vers le bas pour voir les détails de cet exemple d'API avant de choisir Créer une API.

  4. Dans le volet de navigation principal, choisissez Ressources. L'API nouvellement créée est affichée comme suit :

    Exemple d'API après son importation dans la console API Gateway.

    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 la table Méthodes de droite. Le type de méthode, le type d'intégration, le type d'autorisation et la clé d'API requise sont affichés avec chaque méthode.

  5. 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 :

    Méthode POST /pets pour l'exemple d'API dans la console API Gateway.

    Le volet Exécution de la méthode qui en résulte présente une vue logique de la structure et des comportements de la méthode choisie (POST /pets).

    Demande de méthode et Réponse de méthode représentent l'interface de l'API avec le frontend, et Demande d'intégration et Réponse d'intégration représentent l'interface de l'API avec le backend.

    Un client utilise l'API pour accéder à une fonctionnalité backend via Demande de méthode. Si nécessaire, API Gateway convertit la demande du client au format acceptable pour le backend dans 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 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 d'intégration 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 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. Pour le moment, nous nous concentrons sur le test de l'API afin d'offrir une expérience end-to-end utilisateur.

  6. Sélectionnez l'onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.

  7. Par exemple, pour tester la méthode POST /pets, entrez la charge utile {"type": "dog","price": 249.99} suivante dans Corps de la demande avant de choisir Test.

    Testez la méthode POST dans la console API Gateway.

    L'entrée indique les attributs de l'animal que nous voulons ajouter à la liste des animaux de compagnie sur le PetStore site Web.

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

    Résultat du test de la méthode POST dans la console API Gateway.

    L'entrée Journal 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 client autre que la test-invoke-request fonctionnalité API Gateway, vous devez d'abord déployer l'API sur une étape.

  9. Pour déployer l'exemple d'API jusqu'à une étape, choisissez Déployer l'API.

    Utilisez le bouton de déploiement pour déployer votre API afin que les appelants puissent appeler votre API.

  10. Pour Étape, sélectionnez Nouvelle étape, puis entrez test.

  11. (Facultatif) Sous Description, entrez une description.

  12. Choisissez Deploy (Déployer).

  13. Dans le volet Étapes qui s'affiche, sous Détails de l'étape, Appeler une URL affiche l'URL permettant d'invoquer la demande de méthode GET / de l'API.

    Une fois que vous avez créé votre API REST, la console affiche l'URL d'invocation de votre API.

  14. Choisissez l'icône de copie pour copier l'URL d'invocation de votre API, puis saisissez l'URL d'invocation de votre API dans un navigateur Web. Une réponse positive renvoie le résultat, généré à partir du modèle de mappage dans la réponse d'intégration.

  15. Dans le panneau 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 du chemin d’accès.

    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.