Tutoriel : Création d'une API REST avec une intégration HTTP autre que de proxy

Dans ce tutoriel, vous créez une API à partir de zéro à l'aide de la console Amazon API Gateway. Vous pouvez envisager la console comme un studio de conception d'API et l'utiliser pour affiner les fonctions d'API, tester ses comportements, créer l'API et la déployer par étapes.

Création d'une API avec l'intégration HTTP personnalisée

Cette section vous guide tout au long des procédures de création de ressources, d'exposition de méthodes sur une ressource, de configuration d'une méthode pour obtenir les comportements d'API souhaités, et de test et de déploiement de l'API.

Au cours de cette étape, vous créez une API vide. Dans les étapes suivantes, vous allez créer des ressources et des méthodes pour connecter votre API au point de terminaison http://petstore-demo-endpoint.execute-api.com/petstore/pets, à l’aide d’une intégration HTTP sans proxy.

Pour créer une API

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

2. 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).

3. Sous API name (Nom de l'API), saisissez HTTPNonProxyAPI.

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

5. Laissez Type de point de terminaison d'API défini sur Régional.

6. Sélectionnez Create API (Créer une API).

L'arborescence Resources affiche la ressource racine (/) sans aucune méthode. Dans cet exercice, nous allons créer l'API avec l'intégration HTTP personnalisée du PetStore site Web (http ://petstore-demo-endpoint.execute-api.com/petstore/pets.) À des fins d'illustration, nous allons créer une /pets ressource en tant qu'enfant de la racine et exposer une méthode GET sur cette ressource afin qu'un client puisse récupérer une liste des articles Pets disponibles sur le PetStore site Web.

Pour créer une ressource /pets

1. Sélectionnez la ressource /, puis choisissez Créer une ressource.

2. Maintenez Ressource proxy désactivée.

3. Conservez Chemin de la ressource sous la forme /.

4. Sous Resource Name (Nom de la ressource), entrez pets.

5. Maintenez CORS (Partage des ressources entre origines multiples) désactivé.

6. Choisissez Créer une ressource.

Dans cette étape, vous créez une méthode GET pour la ressource /pets. La méthode GET est intégrée au site web http://petstore-demo-endpoint.execute-api.com/petstore/pets. Les autres options disponibles pour une méthode d’API sont les suivantes :

• POST, principalement utilisée pour créer des ressources enfants.

• PUT, principalement utilisée pour mettre à jour les ressources existantes (et, bien que ce ne soit pas recommandé, peut être utilisée pour créer des ressources enfants).

• DELETE, utilisée pour supprimer des ressources.

• PATCH, utilisée pour mettre à jour les ressources.

• HEAD, principalement utilisée dans les scénarios de test. Cette option est comparable à GET, mais ne renvoie pas la représentation de la ressource.

• OPTIONS, qui peut être utilisée par les appelants pour obtenir des informations sur les options de communication disponibles pour le service cible.

Dans la liste HTTP method, vous devez choisir pour la demande d'intégration une méthode HTTP prise en charge par le backend. Pour HTTP ou Mock integration, il est logique que la demande de méthode et la demande d'intégration utilisent le même verbe HTTP. Pour les autres types d'intégration, la demande de méthode utilisera probablement un autre verbe HTTP que la demande d'intégration. Par exemple, pour appeler une fonction Lambda, la demande d'intégration doit utiliser POST pour appeler la fonction, tandis que la demande de méthode peut utiliser n'importe quel verbe HTTP en fonction de la logique de la fonction Lambda.

Pour créer une méthode GET dans la ressource /pets

1. Sélectionnez la ressource /pets.

2. Choisissez Créer une méthode.

3. Pour Type de méthode, sélectionnez GET.

4. Pour Type d’intégration, sélectionnez Intégration HTTP.

5. Maintenez Intégration de proxy HTTP désactivée.

6. Pour Méthode HTTP, sélectionnez GET.

7. Pour URL du point de terminaison, saisissez http://petstore-demo-endpoint.execute-api.com/petstore/pets.

8. Pour Gestion de contenu, sélectionnez Transmettre.

9. Maintenez Délai d’expiration par défaut activé.

10. Choisissez Créer une méthode.

Le PetStore site Web vous permet de récupérer une liste d'Petarticles par type d'animal de compagnie (comme « chien » ou « chat ») sur une page donnée. Il utilise les paramètres de chaîne de requête type et page pour accepter ces entrées. Par conséquent, nous devons ajouter les paramètres de chaîne de requête à la demande de méthode et les mapper aux chaînes de requête correspondantes de la demande d'intégration.

Pour ajouter des paramètres de chaîne de requête à la méthode GET

1. Dans l'onglet Demande de méthode, sous Paramètres de demande de méthode, choisissez Modifier.

2. Choisissez Paramètres de chaîne de requête d’URL, puis procédez comme suit :

   1. Sélectionnez Add query string (Ajouter une chaîne de requêtes).

   2. Pour Nom, saisissez type

   3. Gardez Obligatoire et Mise en cache désactivés.

   Répétez les étapes précédentes pour créer une chaîne de requête supplémentaire avec le nom page.

3. Choisissez Enregistrer.

Le client peut désormais fournir un type d'animal et un numéro de page comme paramètres de chaîne de requête lorsqu'il envoie une demande. Ces paramètres d'entrée doivent être mappés dans les paramètres de chaîne de requête de l'intégration pour transmettre les valeurs d'entrée à notre PetStore site Web dans le backend.

Pour mapper les paramètres d’entrée à la requête d’intégration

1. Dans l’onglet Requête d’intégration, sous Paramètres de requête d’intégration, choisissez Modifier.

2. Choisissez Paramètres de chaîne de requête d’URL, puis procédez comme suit :

   1. Choisissez Ajouter un paramètre de chaîne de requête d’URL.

   2. Pour Name (Nom), saisissez type.

   3. Pour Mappage à partir de, saisissez method.request.querystring.type.

   4. Maintenez Mise en cache désactivée.

   5. Choisissez Ajouter un paramètre de chaîne de requête d’URL.

   6. Pour Name (Nom), saisissez page.

   7. Pour Mappage à partir de, saisissez method.request.querystring.page.

   8. Maintenez Mise en cache désactivée.

3. Choisissez Enregistrer.

Pour tester l'API

1. Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.

2. Pour Chaînes de requête, saisissez type=Dog&page=2.

3. Sélectionnez Tester).

   Le résultat est similaire à ce qui suit :

   

   Maintenant que le test est réussi, nous pouvons déployer l'API pour la rendre disponible publiquement.

4. Sélectionnez Deploy API (Déployer une API).

5. Pour Étape, sélectionnez Nouvelle étape.

6. Sous Stage name (Nom de l'étape), entrez Prod.

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

8. Choisissez Deploy (Déployer).

9. (Facultatif) Sous Détails de l’étape, pour Invoquer une URL, vous pouvez choisir l’icône de copie pour copier l’URL d’invocation de votre API. Vous pouvez l'utiliser avec des outils tels que Postman et cURL pour tester votre API.

Si vous utilisez un kit SDK pour créer un client, vous pouvez appeler les méthodes exposées par ce kit SDK pour signer la demande. Pour en savoir plus sur la mise en œuvre, veuillez consulter le kit SDK AWS de votre choix.

Note

Lorsque des modifications sont apportées à votre API, vous devez la redéployer pour rendre les nouvelles fonctions ou celles mises à jour disponibles avant d'appeler à nouveau l'URL de demande.

(Facultatif) Mapper les paramètres de requête.

Paramètres de demande de mappage pour une API API Gateway

Ce didacticiel montre comment créer un paramètre de chemin {petId} sur l’URL de requête de méthode de l’API pour spécifier un ID d’élément, mappage de celui-ci au paramètre de chemin {id} dans l’URL de requête d’intégration, et envoi de la requête au point de terminaison HTTP.

Note

La saisie d’une lettre majuscule (ou vice versa) peut entraîner des erreurs ultérieurement dans la procédure.

Étape 1 : Créer des ressources

Au cours de cette étape, vous créez une ressource avec un paramètre de chemin {petId}.

Pour créer la ressource {petId}

1. Sélectionnez la ressource /pets, puis choisissez Créer une ressource.

2. Maintenez Ressource proxy désactivée.

3. Pour Chemin de ressource, sélectionnez /pets/.

4. Sous Resource Name (Nom de la ressource), entrez {petId}.

   Encadrez petId par des accolades ({ }) pour afficher /pets/{petId}.

5. Maintenez CORS (Partage des ressources entre origines multiples) désactivé.

6. Choisissez Créer une ressource.

Étape 2 : Créer et tester les méthodes

Au cours de cette étape, vous créez une méthode GET avec un paramètre de chemin {petId}.

Pour configurer la méthode GET

1. Sélectionnez la ressource /{petId}, puis choisissez Créer une méthode.

2. Pour Type de méthode, sélectionnez GET.

3. Pour Type d’intégration, sélectionnez Intégration HTTP.

4. Maintenez Intégration de proxy HTTP désactivée.

5. Pour Méthode HTTP, sélectionnez GET.

6. Pour URL du point de terminaison, saisissez http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}

7. Pour Gestion de contenu, sélectionnez Transmettre.

8. Maintenez Délai d’expiration par défaut activé.

9. Choisissez Créer une méthode.

Vous devez maintenant mapper le paramètre de chemin {petId} au paramètre de chemin {id} dans le point de terminaison HTTP.

Pour mapper le paramètre de chemin {petId}

1. Dans l’onglet Requête d’intégration, sous Paramètres de requête d’intégration, choisissez Modifier.

2. Choisissez paramètres de chemin d’URL.

3. API Gateway crée un paramètre de chemin pour la requête d’intégration nommé petId. Cela ne fonctionnera pas pour votre backend. Le point de terminaison HTTP utilise {id} comme paramètre de chemin. Renommez petId en id.

   Cela mappe le paramètre de chemin petId de la demande de méthode au paramètre de chemin id de la demande d'intégration.

4. Choisissez Enregistrer.

Maintenant, testez la méthode.

Pour tester la méthode 

1. Choisissez l’onglet Test. Vous devrez peut-être choisir la flèche droite pour afficher l'onglet.

2. Sous Chemin pour petId entrez 4.

3. Sélectionnez Test.

   Si le test aboutit, Corps de la réponse affiche les informations suivantes :

   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }

Étape 3 : Déploiement de l'API

Dans cette étape, vous allez déployer l'API afin de pouvoir commencer à l'appeler en dehors de la console API Gateway.

Pour déployer l'API

1. Sélectionnez Deploy API (Déployer une API).

2. Pour Étape, sélectionnez Prod.

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

4. Choisissez Deploy (Déployer).

Étape 4 : Test de l'API

Dans cette étape, vous allez sortir de la console API Gateway et utiliser votre API pour accéder au point de terminaison HTTP.

1. Dans le volet de navigation principal, choisissez Étape.

2. Sous Détails de l'étape, choisissez l'icône de copie pour copier l'URL d'invocation de votre API.

   Elle doit se présenter comme suit :

   https://my-api-id.execute-api.region-id.amazonaws.com/prod

3. Entrez cette URL dans la zone d’adresse d’un nouvel onglet du navigateur et ajoutez /pets/4 à l’URL avant d’envoyer votre requête.

4. Le navigateur retourne ce qui suit :

   {
     "id": 4,
     "type": "bird",
     "price": 999.99
   }

Étapes suivantes

Vous pouvez personnaliser davantage votre API en activant la validation des requêtes, en transformant les données ou en créant des réponses de passerelle client.

Pour découvrir d’autres moyens de personnaliser votre API, consultez les didacticiels suivants :

• Pour plus d'informations sur la validation de demande, consultez Configuration de la validation de demande de base dans API Gateway.

• Pour plus d’informations sur la transformation des charges utiles de requête et de réponse, consultez Configuration de transformations de données dans API Gateway.

• Pour plus d’informations sur la création d’une passerelle client, consultez Configurer une réponse de passerelle pour une API REST à l'aide de la console API Gateway.