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

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d' Apigee Edge.

Points abordés

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

Créer un proxy d'API Apigee à 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

Vous allez apprendre à créer un proxy d'API Apigee à partir d'une spécification OpenAPI à l'aide de l'interface utilisateur d'Apigee. 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

"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 la page Spécification OpenAPI.

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 en savoir plus sur l'ensemble complet des API compatibles avec le service de simulation cible, consultez la page Exemples d'API Apigee.

Prérequis

Avant de commencer, vous devez suivre la procédure décrite sur la page Présentation et prérequis.
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 la page apigee/api-platform-samples.
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

Pour créer le proxy d'API à partir d'une spécification OpenAPI, procédez comme suit :

Si vous utilisez https://console.cloud.google.com/apigee : sélectionnez Développement de proxys > Proxys d'API.

Si vous utilisez la version classique de l'interface utilisateur d'Apigee : sélectionnez Développer > Proxys d'API, puis dans le volet Proxys, sélectionnez l'environnement du proxy.
Dans la fenêtre principale, cliquez sur API Proxies (Proxys d'API).
Vous pouvez également sélectionner Develop > API Proxies (Développer > Proxys d'API) dans le menu de navigation de gauche.
Cliquez sur Créer.
Dans l'assistant Create Proxy (Créer un proxy), cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) pour le modèle Reverse proxy (most common) (Proxy inverse (le plus courant)).
Cliquez sur URL, puis saisissez les informations suivantes :
URL de 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
```

Cliquez sur Select (Sélectionner).

La page Proxy details (Détails du proxy) de l'assistant Create Proxy (Créer un 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 de la spécification OpenAPI :

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 votre nom de domaine externe ou interne, ainsi que ce chemin d'accès de base. Exemple : `http://apitest.acme.com/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
...

Sur la page Proxy details (Détails du proxy), modifiez le champ Description comme suit :
```
API proxy for the Apigee mock target service endpoint.
```
Cliquez sur Suivant.
Sur la page Common policies (Règles courantes), sous Security: Authorization (Sécurité : Autorisation), vérifiez que l'option Pass through (no authorization) (Directe (sans autorisation)) est sélectionnée, puis cliquez sur Next (Suivant) :
Sur la page Flows (Flux), assurez-vous que toutes les opérations sont sélectionnées.
Conseil : Les flux conditionnels sont générés automatiquement à partir des opérations définies dans l'objet paths de la spécification OpenAPI. Les flux conditionnels indiquent à Apigee : "Lorsque vous voyez cela, appliquez cette logique." Par exemple, lorsqu'un appel d'API est une requête GET sur la ressource /xml (la condition), transforme la réponse au format JSON (via une règle associée au flux conditionnel). Un seul flux s'exécute par transaction, à savoir le premier flux dont la condition est définie sur "true".
Cliquez sur Suivant.
Sur la page Résumé, assurez-vous qu'un environnement est sélectionné sous Déploiement facultatif, puis cliquez sur Créer et déployer :

Apigee crée votre proxy d'API et le déploie dans votre environnement :
Cliquez sur Edit proxy (Modifier le proxy) pour afficher la page Overview (Présentation) du proxy d'API.

Tester le proxy d'API

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

où YOUR_ENV_GROUP_HOSTNAME est le nom d'hôte de votre groupe d'environnements. Consultez la section Rechercher le nom d'hôte de votre groupe d'environnements.

Exemple :

curl -v -k https://apitest.acme.com/myproxy

Réponse

La réponse suivante devrait s'afficher :

Hello, Guest!

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.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

où YOUR ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements. Consultez la page Rechercher le nom d'hôte du groupe d'environnements.

Response (Réponse)

La réponse suivante devrait s'afficher :

<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 règle XML à JSON au flux conditionnel de réponse XML dans le proxy d'API.

Nouvel éditeur de proxys

Cliquez sur l'onglet Développer de la page Présentation de l'API Mock Target dans l'interface utilisateur d'Apigee.

Sélectionnez "Afficher la réponse XML"

Dans le volet de gauche, sous Points de terminaison du proxy > Par défaut, cliquez sur le flux conditionnel Afficher la réponse XML.
Dans le volet de gauche, cliquez sur le bouton + de la ligne Règles.
Dans la boîte de dialogue Créer une règle, cliquez dans le champ Sélectionner un type de règle et faites défiler la page jusqu'à Médiation, puis sélectionnez XML à JSON. Conservez les valeurs par défaut des champs Nom à afficher et Nom.
Cliquez sur Créer pour créer la règle.
Cliquez sur le bouton + à côté du flux Afficher la réponse XML dans la réponse.
Dans la boîte de dialogue Ajouter une règle, cliquez dans le champ Sélectionner une règle existante et sélectionnez XML à JSON-1.
Cliquez sur Ajouter. La règle XML vers JSON est appliquée à la réponse.

Pour afficher le code du flux conditionnel Afficher la réponse XML, cliquez sur Passer à l'éditeur de code.
Cliquez sur Enregistrer.

Éditeur de proxy classique

Cliquez sur l'onglet Développer de la page Présentation de l'API Mock Target dans l'interface utilisateur d'Apigee.
Dans le volet de navigation de gauche, sous Proxy Endpoints > Default (Points de terminaison du proxy > Par défaut), cliquez sur le flux conditionnel View XML Response (Afficher la réponse XML).
Cliquez sur le bouton +Step (+ Étape) inférieur, correspondant à la réponse Response du flux.

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.
Faites défiler la page jusqu'à la catégorie Mediation (Médiation), puis sélectionnez XML to JSON (XML vers JSON).
Conservez les valeurs par défaut des champs Display Name (Nom à afficher) et Name (Nom).
Cliquez sur Ajouter. La règle XML vers JSON est appliquée à la réponse.
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 -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

où YOUR ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements. Consultez la page Rechercher le nom d'hôte du groupe d'environnements.

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

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