Construire un proxy d'API simple

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X.
En savoir plus

Apigee Edge vous permet d'exposer rapidement des services de backend en tant qu'API. Pour ce faire, vous devez créer un proxy d'API offrant une façade pour le service de backend que vous souhaitez exposer. Fournissez simplement l'adresse réseau du service de backend, ainsi que certaines informations qu'Edge utilisera pour créer le proxy d'API qui sera exposé aux développeurs.

Le proxy d'API dissocie l'implémentation de votre service de backend de l'API que les développeurs utilisent. L'objectif est de protéger les développeurs des futurs changements qui seront apportés à vos services de backend. Lorsque vous mettrez à jour vos services de backend, les développeurs, tenus à l'écart de ces changements, pourront continuer à appeler l'API sans interruption.

Regardez cette vidéo pour un aperçu du processus de création d'un proxy d'API.

Créer un proxy d'API à l'aide de l'interface utilisateur

Le moyen le plus simple de créer un proxy d'API consiste à utiliser l'assistant de création de proxy.

Edge

Pour accéder à l'assistant de création de proxy à l'aide de l'interface utilisateur Edge:

  1. Connectez-vous à apigee.com/edge.
  2. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  3. Cliquez sur +Proxy.

L'assistant de création de proxy affiche les différentes étapes à suivre pour générer et ajouter des fonctionnalités minimales à un proxy d'API.

La première page de l&#39;assistant de création de proxy vous invite à sélectionner un proxy inverse, un service SOAP, aucune cible ou un groupe de proxys pour personnaliser le flux de l&#39;assistant.

Classic Edge (cloud privé)

Pour accéder à l'assistant de création de proxy à l'aide de l'interface utilisateur Classic Edge:

  1. Connectez-vous à http://ms-ip:9000, où ms-ip est le Adresse IP ou nom DNS du nœud du serveur de gestion.
  2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
  3. Cliquez sur + Proxy d'API.

L'assistant de création de proxy affiche les différentes étapes à suivre pour générer et ajouter des fonctionnalités minimales à un proxy d'API.

La première page de l&#39;assistant de création de proxy vous invite à sélectionner un proxy inverse, un service SOAP, aucune cible ou un groupe de proxys pour personnaliser le flux de l&#39;assistant.

La première page de l'assistant vous permet de créer un proxy d'API à partir des sources suivantes :

Type Description
Proxy inverse (le plus courant)

Un proxy d'API qui achemine les requêtes entrantes vers des services de backend HTTP existants. Il peut s'agir d'une API JSON ou XML. Consultez la section Créer un proxy inverse pour un service HTTP plus loin dans cette section.

Cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) pour générer le proxy à partir d'une spécification OpenAPI valide. Pour plus d'informations sur cette option, consultez la section Utiliser des spécifications OpenAPI pour générer des proxys plus loin sur cette page.

Service SOAP Un proxy d'API généré à partir d'un fichier WSDL. Voir Exposer un service Web basé sur le protocole SOAP en tant que proxy d'API.
Aucune cible

Un proxy d'API sans backend de l'API ("aucune cible"). Cette méthode s'apparente à la création d'un proxy inverse pour un service HTTP décrite précédemment, sauf que vous ne devez pas spécifier une API existante lorsque vous définissez les détails du proxy d'API.

Cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) pour générer le proxy à partir d'une spécification OpenAPI valide. Pour plus d'informations sur cette option, consultez la section Utiliser des spécifications OpenAPI pour générer des proxys plus loin sur cette page.

Cible hébergée

Proxy d'API qui achemine vers une application Node.js déployée dans l'environnement de cibles hébergées Consultez la section Présentation des cibles hébergées.

Importer le groupe de proxys Un groupe de proxys d'API existant (par exemple, l'un des exemples de proxys d'API disponibles sur GitHub). Voir Importer un proxy d'API à partir d'un groupe de proxys d'API.

Les sections suivantes décrivent comment créer un proxy d'API à l'aide de chaque source.

Créer un proxy inverse pour un service HTTP

Edge génère des proxy inverses basés sur deux types d'informations:

  • URL du service de backend
  • Chemin d'URI qui identifie de manière unique l'API qui sera exposée par le proxy d'API aux applications grand public

L'URL du service de backend représente généralement une application compatible avec le service appartenant à votre organisation. Elle peut également pointer vers une API accessible au public. Il peut s'agir d'une API ou d'un service que vous contrôlez (par exemple, une application RH interne ou une application Rails dans le cloud), ou bien d'une API ou d'un service tiers (par exemple, Twitter ou Instagram).

Edge

  1. Accédez à l'assistant de création de proxy, comme décrit dans Créer un proxy d'API à l'aide de l'interface utilisateur précédemment décrite dans cette section.
  2. Dans l'assistant de création de proxy, cliquez sur Proxy inverse (le plus courant). Pour générer le proxy à partir d'une spécification OpenAPI existante, cliquez sur Utiliser la spécification OpenAPI. Pour en savoir plus sur cette option, consultez la section Utiliser des spécifications OpenAPI pour générer des proxys ci-dessous.
  3. Sur la page Détails de l'assistant, saisissez les informations suivantes.
    Champ Description
    Nom Nom affiché pour votre API. Indiquez des caractères alphanumériques, des tirets (-) ou des traits de soulignement (_).
    Chemin de base

    Fragment d'URI qui apparaît après l'adresse http(s)://[host] du proxy d'API. Edge utilise l'URI du chemin de base pour faire correspondre et acheminer les messages de requête entrants au proxy d'API approprié.

    REMARQUE: Le chemin de base du proxy d'API est défini par défaut sur la valeur spécifiée pour le champ Name est converti tout en minuscules.

    Le chemin de base est suivi des URL de ressource. Voici la structure d'URL complète que les clients utiliseront pour appeler votre proxy d'API:

    https://[host]/base_path/conditional_flow_path

    REMARQUE: Le chemin d'accès de base doit être unique. vous ne pouvez pas déployer deux proxys d'API avec le même chemin de base. Si vous modifiez un proxy d'API déployé et définissez le chemin de base sur la même valeur que le chemin de base d'un autre proxy d'API, Edge annule automatiquement le déploiement au proxy d'API lorsque vous l'enregistrez. Pour pouvoir redéployer le proxy d'API, vous devez modifier le chemin d'accès de base afin qu'il soit unique.

    Utiliser des caractères génériques dans les chemins de base

    Utilisez un ou plusieurs caractères génériques /*/ dans les chemins d'accès de base du proxy d'API pour assurer la pérennité de vos proxys d'API. Par exemple, un chemin de base de /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer de proxys d'API pour gérer les nouvelles équipes. Notez que /**/ n'est pas accepté.

    Description (Facultatif) Description de l'API.
    Cible (API existante) URL du service de backend que ce proxy d'API appelle.
  4. Sur la page Règles communes de l'assistant, configurez les éléments suivants :
    • Exigences d'autorisations de sécurité sous Sécurité: Autorisation. Consultez la section Ajout de sécurité plus loin dans cette section.
    • Compatibilité du partage des ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) sous Sécurité : navigateur. Voir Ajout de la compatibilité avec CORS plus loin dans cette section.
    • Quotas visant à protéger votre service de backend contre le trafic élevé sous Quota. Consultez la section Quotas. (Non disponible si l'autorisation directe est sélectionnée).
    • Application des limites de monétisation pour les organisations ayant activé la monétisation sous Monétisation. Voir Appliquer des limites de monétisation au niveau des proxys d'API.
  5. Sur la page Hôtes virtuels de l'assistant, sélectionnez les hôtes virtuels qui seront liés au proxy d'API lors du déploiement. Pour plus d'informations, consultez la section À propos des hôtes virtuels.
  6. Sur la page Résumé, sélectionnez un ou plusieurs environnements de déploiement, si vous le souhaitez, puis cliquez sur Créer et déployer.

    Votre proxy d'API est créé et déployé dans l'environnement sélectionné.

  7. Cliquez sur Modifier le proxy pour afficher la page d'informations du proxy d'API.

Classic Edge (cloud privé)

  1. Accédez à l'assistant de création de proxy, comme décrit dans Créer un proxy d'API à l'aide de l'interface utilisateur précédemment décrite dans cette section.
  2. Dans l'assistant Créer un proxy, sélectionnez Proxy inverse (le plus courant). À générer le proxy à partir d'une spécification OpenAPI valide existante, puis cliquer sur Use OpenAPI (Utiliser OpenAPI). Pour en savoir plus sur cette option, consultez la section Utiliser des spécifications OpenAPI pour générer des proxys ci-dessous.
  3. Cliquez sur Suivant.
  4. Sur la page Détails de l'assistant, saisissez les informations suivantes.
    Champ Description
    Nom du proxy Nom affiché pour votre API.
    Chemin de base du proxy

    Le chemin de base du proxy est un fragment d'URI après l'adresse http(s)://[host] de votre proxy d'API. Edge utilise l'URI du chemin de base pour faire correspondre et acheminer les messages de requête entrants au proxy d'API approprié.

    Remarque: Pour obtenir des recommandations d'Apigee sur la gestion des versions d'API, consultez Gestion des versions dans le livre Web API Design: The Missing Link numérique.

    Les URL de ressources supplémentaires sont suivies du chemin de base. Voici l'URL complète structure que les clients utiliseront pour appeler votre proxy d'API:

    https://[host]/base_path/conditional_flow_path

    Remarque: Le chemin de base doit être unique. Si vous modifiez ce proxy ultérieurement et définir son chemin de base pour qu'il soit identique à celui d'un autre proxy d'API, ce proxy d'API est automatiquement annulée lorsque vous l'enregistrez. Vous devez modifier le chemin de base avant vous pouvez le redéployer.

    Utiliser un caractère générique dans les chemins de base

    Vous pouvez utiliser un ou plusieurs caractères génériques /*/ dans les chemins de base des proxys d'API pour pérenniser vos proxys. Par exemple, un chemin d'accès de base /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans vous besoin de créer de nouveaux proxys d'API pour prendre en charge de nouvelles équipes. Notez que /**/ n'est pas compatibles.

    Remarque: Le chemin de base du proxy est défini par défaut sur la valeur spécifiée pour Le nom du proxy est converti tout en minuscules, sauf si vous modifiez explicitement le contenu dans Chemin de base du proxy.

    API existante URL que la plate-forme API appelle au nom des applications qui appellent votre API via l'URL du proxy d'API.
    Description Description de l'API.
  5. Sur la page Sécurité de l'assistant, configurez les éléments suivants: <ph type="x-smartling-placeholder">
  6. Sur la page Virtual Hosts (Hôtes virtuels) de l'assistant, sélectionnez les hôtes virtuels auxquels le proxy d'API sera lié lors du déploiement. Pour plus d'informations, consultez la section À propos des hôtes virtuels.
  7. Sélectionnez le ou les environnements de déploiement, puis cliquez sur Build and Deploy(Compiler et déployer).
    Un accusé de réception vous est envoyé pour confirmer que le proxy d'API a bien été créé. et déployés dans l'environnement sélectionné.
  8. Cliquez sur Afficher le nom de <nom du proxy>. dans l'éditeur pour afficher la page des détails du proxy d'API.

Importer un proxy d'API à partir d'un groupe de proxys d'API

Les proxys d'API sont souvent définis comme des ensembles de fichiers XML accompagnés d'autres fichiers sources. En définissant vos proxys d'API en tant qu'ensemble de fichiers extérieurs à Edge, vous pouvez les conserver dans un système contrôlé par la source, puis les importer dans Edge à des fins de test et de déploiement.

Regardez cette vidéo pour apprendre à créer et à importer un proxy d'API à partir d'un groupe de proxys d'API.

Edge

Pour importer des proxys d'API à partir d'un groupe de proxys d'API:

  1. Accédez à l'assistant de création de proxy, comme décrit dans Créer un proxy d'API à l'aide de l'interface utilisateur précédemment décrite dans cette section.
  2. Cliquez sur Importer le groupe de proxys.
  3. Sur la page Importer le groupe de proxys de l'assistant de proxy, saisissez les informations suivantes.

    Champ Description
    Dossier ZIP Fichier ZIP contenant la configuration du proxy d'API. Accédez au fichier par glisser-déposer ou en effectuant un clic.
    Nom Nom affiché pour votre API. Correspond par défaut au nom du fichier ZIP sans l'extension.
  4. Cliquez sur Suivant.
  5. Sur la page Résumé, sélectionnez un ou plusieurs environnements de déploiement, si vous le souhaitez, puis cliquez sur Créer et déployer.
    Un accusé de réception s'affiche pour confirmer que votre proxy d'API a bien été créé.
  6. Cliquez sur Modifier le proxy pour afficher la page d'informations du proxy d'API.

Classic Edge (cloud privé)

  1. Accédez à l'assistant de création de proxy, comme décrit dans Créer un proxy d'API à l'aide de l'interface utilisateur précédemment décrite dans cette section.
  2. Dans l'assistant "Créer un proxy", sélectionnez Groupe de proxy.
  3. Cliquez sur Suivant.
  4. Sur la page Details (Détails) de l'assistant de proxy, saisissez les informations suivantes.

    Champ Description
    Pack ZIP Cliquez sur Choose File (Sélectionner un fichier) et accédez au fichier ZIP contenant la configuration du proxy d'API.
    Nom du proxy Nom affiché pour votre API.
  5. Vérifiez les informations sur la compilation, puis cliquez sur Build (Compiler).
    Si l'opération réussit, un message s'affiche et Edge déploie automatiquement le proxy d'API importé dans l'environnement sélectionné. dans votre organisation. Il est maintenant possible d'appeler l'API exposée par le proxy d'API.
  6. Cliquez sur Afficher le <nom du proxy> proxy dans l'éditeur pour afficher la page des détails du proxy d'API.
  7. Pour déployer le proxy, cliquez sur la liste déroulante Deployment (Déploiement), puis sélectionnez le l'environnement dans lequel vous souhaitez effectuer le déploiement et répondez à l'invite.

Exposer un service Web basé sur SOAP en tant que proxy d'API

Dans l'assistant de création de proxy, cliquez sur Service SOAP et suivez les instructions de l'assistant pour créer un proxy pass-through ou basé sur REST pour un service SAP. Pour en savoir plus, consultez la section Exposer un service SOAP en tant que proxy d'API.

Ajout de sécurité

Sur la page Règles communes (Edge) ou Sécurité (Classic Edge) de l'assistant de création de proxy, sélectionnez le type d'autorisation de sécurité que vous souhaitez ajouter. Le tableau suivant récapitule les options disponibles :

Autorisation de sécurité Description
Clé API Ajoute une validation de clé API simple au proxy d'API que vous définissez. En réponse, la plate-forme d'API ajoute une règle VerifyAPIKey et une règle AssignMessage à votre proxy d'API. La règle VerifyAPIKey valide les clés API présentées par les applications demandeuses. La règle AssignMessage supprime la clé API, fournie dans l'appel d'API en tant que paramètre de requête, de la requête transmise au serveur backend.
OAuth 2.0 Ajoute l'authentification basée sur OAuth 2.0 à votre proxy d'API. Apigee Edge ajoute automatiquement deux stratégies à votre proxy d'API: une pour vérifier un jeton d'accès et une autre pour supprimer le jeton d'accès du message avant de la transférer à votre service de backend. Pour savoir comment obtenir un jeton d'accès, consultez la page OAuth.
Directe (sans autorisation) Aucune autorisation requise. Les requêtes sont transmises au backend sans aucun contrôle de sécurité sur Apigee Edge.

Assurer la compatibilité avec CORS

CORS (Cross-Origin Resource Sharing) est un mécanisme standard qui permet à un navigateur Web d'effectuer des de diriger les requêtes vers un autre domaine. La norme CORS définit un ensemble d'en-têtes HTTP que les navigateurs et les serveurs utilisés pour implémenter la communication entre domaines.

Vous pouvez permettre la compatibilité entre CORS et votre API en sélectionnant Ajouter des en-têtes CORS dans la zone règles communes (Edge) ou Sécurité (Classic Edge) de l'assistant de création de proxy.

Pour plus d'informations sur la compatibilité CORS, y compris l'ajout de la compatibilité CORS préliminaire à un proxy, consultez la page Ajouter la compatibilité CORS à un proxy d'API.

Utiliser des spécifications OpenAPI pour générer des proxys

Cette section traite de l'option "Utiliser OpenAPI" disponible pour générer à partir d'une clé OpenAPI Spécification des types de proxys d'API suivants: reverse, Node.js ou no target.

Qu'est-ce qu'une spécification OpenAPI ?

Logo 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. La spécification décrit de tels éléments d'une API, en tant que chemin de base, 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.

Voici un fragment d'une spécification OpenAPI décrivant le service cible fictif d'Apigee : http://mocktarget.apigee.net. Pour en savoir plus, consultez la page https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

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
  /help:
    get:
      summary: Get help
      operationId: Get help
      description: View help information about available resources in HTML format.
      responses:
        "200":
          description: Success
...

Avec l'assistant de création de proxy, vous pouvez importer une spécification OpenAPI et l'utiliser pour générer un proxy d'API. Une fois le proxy généré, vous pouvez utiliser l'interface utilisateur Edge pour le développer davantage en ajoutant des règles, en mettant en œuvre du code personnalisé, et plus encore, comme vous pourriez le faire sur n'importe quel proxy Edge.

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

Créez vos proxys d'API à partir d'une spécification OpenAPI. En quelques clics, vous obtenez un proxy d'API avec les chemins, paramètres, flux conditionnels et points de terminaison cibles générés automatiquement. Vous pouvez ensuite ajouter des fonctionnalités telles que la sécurité OAuth, la limitation du débit et la mise en cache.

Dans l'assistant de création de proxy, cliquez sur Use OpenAPI Spec (Utiliser la spécification OpenAPI) et suivez l'assistant pour créer un proxy inverse ou sans cible à partir d'une spécification OpenAPI. Pour plus d'informations, consultez la page Créer un proxy d'API à partir d'une spécification OpenAPI.

Regardez cette vidéo pour apprendre à créer un proxy d'API à partir d'une spécification OpenAPI.

Mettre à jour les flux dans un proxy d'API à l'aide d'une spécification OpenAPI

Une fois que vous avez créé un proxy d'API à partir d'une spécification OpenAPI, si vous la modifiez pour ajouter des chemins de ressources supplémentaires, vous pouvez l'utiliser pour ajouter les flux conditionnels associés au proxy d'API.

Mettre à jour les flux dans un proxy d'API à l'aide d'une spécification OpenAPI:

  1. Ajoutez les nouveaux chemins d'accès aux ressources à la spécification OpenAPI. Consultez la section Modifier une spécification OpenAPI existante.
  2. Ouvrez le proxy d'API dans l'interface utilisateur et cliquez sur l'onglet Développer.
  3. Dans le navigateur, cliquez sur + à côté du point de terminaison du proxy que vous souhaitez mettre à jour.
    La boîte de dialogue "Nouveau flux conditionnel" s'ouvre.
  4. Cliquez sur From OpenAPI (À partir d'OpenAPI) si cette option n'est pas déjà sélectionnée.
    Si des ressources de la spécification OpenAPI ne possèdent pas de flux conditionnel correspondant dans le proxy d'API, elles sont répertoriées dans la boîte de dialogue, comme illustré dans la figure suivante. Ressources qui ne sont pas représentées comme des flux dans le proxy d&#39;API actuel. Cet exemple inclut /loveapis, /ip, /json et /xml.
  5. Sélectionnez chacune des ressources pour lesquelles vous souhaitez ajouter un flux conditionnel.
  6. Cliquez sur Ajouter.

Les flux conditionnels sont ajoutés à votre proxy d'API.

Créer une révision d'un proxy d'API

Créez une révision d'un proxy d'API, comme décrit ci-dessous.

Edge

Pour créer une nouvelle révision d'un proxy d'API à l'aide de l'interface utilisateur Edge:

  1. Connectez-vous à apigee.com/edge.
  2. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  3. Dans la liste, cliquez sur le proxy d'API que vous souhaitez copier.
  4. Sélectionnez Project > Save as New Revision (Projet > Enregistrer en tant que nouvelle révision).

Classic Edge (cloud privé)

Pour créer une nouvelle révision d'un proxy d'API à l'aide de l'interface utilisateur Classic Edge:

  1. Connectez-vous à http://ms-ip:9000, où ms-ip est le Adresse IP ou nom DNS du nœud du serveur de gestion.
  2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
  3. Dans la liste, cliquez sur le proxy d'API que vous souhaitez copier.
  4. Sélectionnez Project > Save as New Revision (Projet > Enregistrer en tant que nouvelle révision).

Copier un proxy d'API

Copiez un proxy d'API existant vers un nouveau proxy d'API, comme décrit ci-dessous.

Edge

Pour copier un proxy d'API à l'aide de l'interface utilisateur Edge:

  1. Connectez-vous à apigee.com/edge.
  2. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  3. Dans la liste, cliquez sur le proxy d'API que vous souhaitez copier.
  4. Sélectionnez Project > Save as New API Proxy (Projet > Enregistrer en tant que nouveau proxy d'API).
  5. Dans la boîte de dialogue Save as New Proxy (Enregistrer en tant que nouveau proxy), saisissez le nom du nouveau proxy API.
  6. Cliquez sur Ajouter.

Classic Edge (cloud privé)

Pour copier un proxy d'API à l'aide de l'interface utilisateur Classic Edge:

  1. Connectez-vous à http://ms-ip:9000, où ms-ip est le Adresse IP ou nom DNS du nœud du serveur de gestion.
  2. Sélectionnez API > Proxies d'API dans la barre de navigation supérieure.
  3. Dans la liste, cliquez sur le proxy d'API que vous souhaitez copier.
  4. Sélectionnez Project > Save as New API Proxy (Projet > Enregistrer en tant que nouveau proxy d'API).
  5. Dans la boîte de dialogue Save as New Proxy (Enregistrer en tant que nouveau proxy), saisissez le nom du nouveau proxy API.
  6. Cliquez sur Ajouter.

Sauvegarder un proxy d'API

Vous pouvez sauvegarder un proxy d'API existant sous la forme d'un ensemble de fichiers XML dans un groupe de proxys d'API. Une fois le proxy d'API exporté vers un groupe, vous pouvez l'importer dans un nouveau proxy, comme décrit dans la section Importer un proxy d'API à partir d'un groupe de proxys d'API plus haut sur cette page. Pour plus d'informations, consultez la page Télécharger des proxys d'API.

Créer un proxy d'API à l'aide de l'API

Pour créer un proxy d'API à l'aide de l'API, consultez API de proxys d'API.