Créer un proxy d'API à partir d'une spécification OpenAPI

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Points abordés

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

  • Créer un proxy d'API Edge à partir d'une spécification OpenAPI ;
  • Appeler le proxy d'API à l'aide de cURL ;
  • Ajouter une règle à un flux conditionnel ;
  • Tester l'appel de la règle à l'aide de cURL.

Dans ce tutoriel, vous apprendrez à créer un proxy d'API Edge à partir d'une spécification OpenAPI à l'aide de l'interface utilisateur de gestion Apigee Edge. Lorsque vous appelez le proxy d'API avec un client HTTP, tel que cURL, le proxy d'API envoie la demande au service de simulation cible Apigee.

À propos de l'Open API Initiative

Open API Initiative
L'Open API Initiative (OAI) se concentre sur la création, l'évolution et la promotion d'un format de description d'API neutre du point de vue du fournisseur, basé sur la spécification Swagger." Pour en savoir plus sur l'Open API Initiative, consultez le site https://openapis.org.

Une spécification OpenAPI utilise un format standard pour décrire une API RESTful. Développées au format JSON ou YAML, les spécifications OpenAPI sont lisibles par une machine, mais sont également faciles à lire et à comprendre pour les humains. La spécification décrit des éléments d'une API, tels que son chemin de base, ses chemins et verbes, en-têtes, paramètres de requête, opérations, types de contenus, modèles de réponse, etc. En outre, une spécification OpenAPI est couramment utilisée pour générer la documentation de l'API.

À propos du service de simulation cible Apigee

Le service de simulation cible Apigee utilisé dans ce tutoriel est hébergé sur Apigee et renvoie des données simples. Il ne nécessite aucune clé d'API ni jeton d'accès. En fait, vous pouvez y accéder dans un navigateur Web. Essayez-le en cliquant sur les éléments suivants :

http://mocktarget.apigee.net

Le service cible renvoie le message d'accueil Hello, guest!.

Pour plus d'informations sur l'ensemble complet des API compatibles avec le service de simulation cible, cliquez sur le lien suivant :

http://mocktarget.apigee.net/help

Ce dont vous avez besoin

  • Un compte Apigee Edge. Si vous n'avez pas de compte, vous pouvez vous inscrire en suivant les instructions de la section Créer un compte Apigee Edge.
  • Une spécification OpenAPI. Dans ce tutoriel, vous allez utiliser la spécification OpenAPI mocktarget.yaml qui décrit le service de simulation d'Apigee, http://mocktarget.apigee.net. Pour en savoir plus, consultez les pages suivantes : https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi
  • cURL installé sur votre machine pour effectuer des appels d'API à partir de la ligne de commande. ou d'un navigateur Web.

Créer le proxy d'API

Périphérie

Pour créer le proxy d'API à partir d'une spécification OpenAPI à l'aide de l'interface utilisateur Edge:

  1. Connectez-vous à https://apigee.com/edge.
  2. Cliquez sur API Proxies dans la fenêtre principale.

    Vous pouvez également sélectionner Develop > API Proxies (Développer > Proxys d'API) dans la barre de navigation de gauche.

    Cliquer sur "API Proxies" (Proxys d'API) sur la page de destination

  3. Cliquez sur + Proxy.
    Ajouter un proxy d'API
  4. Dans l'assistant "Créer un proxy", cliquez sur Utiliser la spécification OpenAPI pour le modèle Proxy inverse (le plus courant).
    Créer un type de proxy
  5. Cliquez sur Importer à partir de l'URL, puis saisissez les informations suivantes :
    • OpenAPI Spec URL (URL de la spécification OpenAPI) : chemin d'accès au contenu brut sur GitHub pour la spécification OpenAPI dans le champ URL : 
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • Nom de la spécification : nom de la spécification OpenAPI, tel que Mock Target.

      Ce nom est utilisé pour stocker la spécification OpenAPI dans le magasin de spécifications. Consultez la section Gérer vos spécifications.

  6. Cliquez sur Importer.

    La page "Détails" de l'assistant de création de proxy s'affiche. Les champs sont préremplis à l'aide des valeurs définies dans la spécification OpenAPI, comme illustré ci-dessous :

    Le tableau suivant décrit les valeurs par défaut qui sont préremplies à l'aide des propriétés de la spécification OpenAPI. Un extrait de la spécification OpenAPI illustrant les propriétés utilisées est présenté après le tableau.

    Champ Description Par défaut
    Nom Nom du proxy de l'API. Exemple : Mock-Target-API. Propriété title de la spécification OpenAPI avec des espaces remplacés par des tirets
    Chemin de base Composant de chemin d'accès qui identifie ce proxy d'API de manière unique au sein de l'organisation. L'URL publique de ce proxy d'API comprend le nom de votre organisation, un environnement dans lequel ce proxy d'API est déployé et ce chemin d'accès de base. Par exemple : http://myorg-test.apigee.net/mock-target-api. Contenu du champ Name (Nom) converti en minuscules
    Description Description du proxy d'API. Propriété description de la spécification OpenAPI
    Cible (API existante) URL cible appelée au nom de ce proxy d'API. Toute URL accessible via Internet peut être utilisée. Exemple : http://mocktarget.apigee.net Propriété servers de la spécification OpenAPI

    Vous trouverez ci-dessous un extrait de la spécification OpenAPI montrant les propriétés utilisées pour préremplir les champs.

    openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  7. Modifiez le champ Description comme suit : API proxy for the Apigee mock target service endpoint.
  8. Cliquez sur Suivant.
  9. Sur la page Règles communes, sous "Sécurité: Autorisation", assurez-vous que l'option Passthrough (no authorization) est sélectionnée, puis cliquez sur Suivant:

    "Stratégie directe (sans autorisation)" sélectionnée sur la page "Règles courantes"

  10. Sur la page "Flux", assurez-vous que toutes les opérations sont sélectionnées. Créer des flux de proxy
  11. Cliquez sur Suivant.
  12. Sur la page Hôtes virtuels, sélectionnez par défaut et sécurisé, puis cliquez sur Suivant.
    sélectionné "par défaut" et "sécurisé" sur la page "Hôtes virtuels"
  13. Sur la page Summary (Résumé), assurez-vous que l'environnement Test est sélectionné sous Optional Deployment (Déploiement facultatif), puis cliquez sur Create and deploy (Créer et déployer) :

    Apigee crée votre proxy d'API et le déploie dans votre environnement de test:

  14. Cliquez sur Modifier le proxy pour afficher la page de présentation du proxy d'API.
    Récapitulatif du proxy d'API de simulation cible

Classic Edge (cloud privé)

Pour créer le proxy d'API à partir d'une spécification OpenAPI à l'aide de l'interface utilisateur Classic Edge:

  1. Connectez-vous à https://apigee.com/edge.
  2. Cliquez sur API Proxies dans la fenêtre principale.

    Vous pouvez également sélectionner Develop > API Proxies (Développer > Proxys d'API) dans la barre de navigation de gauche.

  3. Cliquez sur + Proxy.
    Ajouter un proxy d'API
  4. Dans l'assistant "Créer un proxy", sélectionnez Proxy inverse (le plus courant), puis cliquez sur Utiliser OpenAPI.
    Créer un type de proxy
  5. Cliquez sur Import from a URL (Importer à partir d'une URL), saisissez un nom pour la spécification OpenAPI, puis indiquez dans le champ URL le chemin d'accès au contenu brut sur GitHub pour la spécification OpenAPI:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. Cliquez sur Sélectionner.
  7. Cliquez sur Suivant.

    La page "Détails" de l'assistant de création de proxy s'affiche. Les champs sont préremplis à l'aide des valeurs définies dans la spécification OpenAPI, comme illustré dans la figure suivante.

    Détails de la création d'un proxy

    Le tableau suivant décrit les valeurs par défaut qui sont préremplies à l'aide des propriétés de la spécification OpenAPI. Un extrait de la spécification OpenAPI illustrant les propriétés utilisées est présenté après le tableau.

    Champ Description Par défaut
    Proxy Name (Nom du proxy) Nom du proxy de l'API. Exemple : Mock-Target-API. Propriété title de la spécification OpenAPI avec des espaces remplacés par des tirets
    Chemin de base du proxy Composant de chemin d'accès qui identifie ce proxy d'API de manière unique au sein de l'organisation. L'URL publique de ce proxy d'API comprend le nom de votre organisation, un environnement dans lequel ce proxy d'API est déployé et ce chemin d'accès de base. Par exemple : http://myorg-test.apigee.net/mock-target-api. Contenu du champ Name (Nom) converti en minuscules
    Existing API (API existante) URL cible appelée au nom de ce proxy d'API. Toute URL accessible via Internet peut être utilisée. Exemple : http://mocktarget.apigee.net Propriété servers de la spécification OpenAPI
    Description Description du proxy d'API. Propriété description de la spécification OpenAPI

    Vous trouverez ci-dessous un extrait de la spécification OpenAPI montrant les propriétés utilisées pour préremplir les champs.

    openapi: 3.0.0
info:
  description: OpenAPI Specification for the Apigee mock target service endpoint.
  version: 1.0.0
  title: Mock Target API
paths:
  /:
    get:
      summary: View personalized greeting
      operationId: View a personalized greeting
      description: View a personalized greeting for the specified or guest user.
      parameters:
        - name: user
          in: query
          description: Your user name.
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Success
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  8. Modifiez le champ Description comme suit : API proxy for the Apigee mock target service endpoint.
  9. Cliquez sur Suivant.
  10. Sur la page "Flux", assurez-vous que toutes les opérations sont sélectionnées. Créer des flux de proxy
  11. Cliquez sur Suivant.
  12. Sur la page "Sécurité", sélectionnez l'option de sécurité Passthrough (none), puis cliquez sur Suivant.
  13. Sur la page "Hôtes virtuels", vérifiez que tous les hôtes virtuels sont sélectionnés, puis cliquez sur Suivant.
  14. Sur la page "Créer", assurez-vous que l'environnement de test est sélectionné, puis cliquez sur Créer et déployer.
  15. Sur la page "Summary" (Résumé) vous indique que votre nouveau proxy d'API a bien été créé et déployé dans votre environnement de test.
    Récapitulatif sur la création d'un proxy
  16. Cliquez sur Mock-Target-API pour afficher la page de présentation du proxy d'API.
    Récapitulatif du proxy d'API de simulation cible

Félicitations ! Vous avez créé un proxy d'API à partir d'une spécification OpenAPI. Vous allez maintenant le tester pour voir comment cela fonctionne.

Tester le proxy d'API

Vous pouvez tester votre API Mock-Target-API à l'aide de cURL ou d'un navigateur Web.

Dans une fenêtre de terminal, exécutez la commande cURL suivante. Remplacez le nom de votre organisation dans l'URL.

curl http://<org_name>-test.apigee.net/mock-target-api

Réponse

Vous devriez voir la réponse suivante :

Hello, Guest!

Bravo ! Vous avez créé un proxy d'API simple à partir d'une spécification OpenAPI et l'avez testé.

Ajouter une règle XML vers JSON

Vous allez ensuite ajouter la règle XML à JSON au flux conditionnel View XML Response (Afficher la réponse XML) généré automatiquement lorsque vous avez créé le proxy d'API à partir de la spécification OpenAPI. La règle convertit la réponse XML de la cible en réponse JSON.

Commencez par appeler l'API afin de pouvoir comparer les résultats avec ceux reçus après l'ajout de la règle. Dans une fenêtre de terminal, exécutez la commande cURL suivante. Vous appelez la ressource /xml du service cible, qui renvoie de manière native un bloc XML simple. Remplacez le nom de votre organisation dans l'URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Réponse

Vous devriez voir la réponse suivante :

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Essayons maintenant d'effectuer la conversion d'une réponse XML au format JSON. Ajoutez la stratégie XML à JSON au flux conditionnel de réponse XML dans le proxy d'API.

  1. Cliquez sur l'onglet Develop (Développer) dans le coin supérieur droit de la page de présentation de l'API Mock-Target-API dans l'interface utilisateur Edge.
    Onglet &quot;Développeur&quot;
  2. Dans le volet de navigation de gauche, sous Points de terminaison du proxy > par défaut, cliquez sur le flux conditionnel Afficher la réponse XML.
    Sélectionnez &quot;Afficher la réponse XML&quot;
  3. Cliquez sur le bouton +Step (+ Étape) inférieur, correspondant à la réponse Response du flux.
    Sélectionner &quot;+Step&quot; (+ Étape)
    La boîte de dialogue "Add Step" ("Ajouter une étape") s'ouvre. Elle contient une liste de toutes les règles que vous pouvez ajouter classées par catégories.
  4. Faites défiler la page jusqu'à la catégorie "Médiation" et sélectionnez XML to JSON.
    Boîte de dialogue &quot;Add Step&quot; (&quot;Ajouter une étape&quot;)
  5. Conservez les valeurs par défaut pour Display Name (Nom à afficher) et Name (Nom).
  6. Cliquez sur Add (Ajouter). La règle XML vers JSON est appliquée à la réponse.Règle XML vers JSON dans le flux
  7. Cliquez sur Enregistrer.

Maintenant que vous avez ajouté la règle, appelez à nouveau l'API à l'aide de cURL. Notez que vous appelez toujours la même ressource /xml. Le service cible renvoie toujours son bloc de code XML, mais la règle du proxy d'API convertit désormais la réponse au format JSON. Effectuez l'appel suivant :

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Notez que la réponse XML est convertie au format JSON :

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Félicitations ! Vous avez réussi à tester l'exécution d'une règle ajoutée à un flux conditionnel.