Concepts relatifs à API Gateway

Dans le service API Gateway, une passerelle d'API désigne une appliance virtuelle réseau au sein d'un sous-réseau régional.

Une passerelle d'API achemine le trafic entrant vers les services back-end, y compris les API HTTP publiques, privées et partenaires, ainsi que vers OCI Functions. Chaque passerelle d'API est une adresse privée que vous pouvez éventuellement rendre visible sur une adresse IP publique en tant que passerelle d'API publique:

• Une passerelle d'API privée n'est accessible que par les ressources du même réseau privé (VCN) ou par les ressources d'un autre réseau privé ou sur site appairé à ce réseau privé. Une passerelle d'API privée dispose d'une adresse IP privée et d'un nom d'hôte généré automatiquement au format <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Bien que le nom d'hôte puisse être résolu publiquement à partir d'Internet, il est résolu en adresse IP privée de la passerelle d'API. Le trafic vers l'adresse IP privée n'est pas routable à partir du réseau Internet public ; seuls les clients du VCN peuvent accéder à la passerelle d'API. La capacité de résolution DNS publique d'une adresse IP privée est attendue, prenant en charge diverses configurations de réseau dans les environnements OCI.
• Une passerelle d'API publique est accessible publiquement et peut être atteinte à partir d'Internet, à condition qu'une passerelle Internet soit présente dans le VCN de la passerelle d'API. Une passerelle d'API publique dispose à la fois d'une adresse IP privée et d'une adresse IP publique, et d'un nom d'hôte généré automatiquement au format <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Le nom d'hôte généré est résolu à partir d'Internet vers l'adresse IP publique, ce qui permet aux clients Internet d'accéder à la passerelle d'API.

Afin de garantir une haute disponibilité, vous pouvez uniquement créer des passerelles d'API dans des sous-réseaux régionaux (et non dans des sous-réseaux propres à un domaine de disponibilité). Vous pouvez créer des passerelles d'API privées dans des sous-réseaux privés ou publics. En revanche, vous ne pouvez créer des passerelles d'API publiques que dans des sous-réseaux publics. Le service API Gateway a une portée régionale et tolère les pannes sur l'ensemble des domaines de disponibilité (dans les régions à plusieurs domaines de disponibilité) et sur les domaines de pannes (dans les régions à un seul domaine de disponibilité). Dans les régions à plusieurs domaines de disponibilité, le service API Gateway sélectionne automatiquement un domaine de disponibilité actif pour mettre fin à l'adresse de passerelle d'API. En fonction de la source et de la destination du trafic, le trafic peut être acheminé entre les domaines de disponibilité. En cas d'échec d'un domaine de disponibilité ou d'un domaine de pannes, le service API Gateway gère automatiquement le basculement et achemine le trafic vers un domaine de disponibilité ou un domaine de pannes en fonctionnement.

Une passerelle d'API est liée à une carte d'interface réseau virtuelle spécifique.

Vous pouvez créer une passerelle d'API dans un compartiment de votre location. Chaque passerelle d'API comporte un seul composant frontal. Elle peut également comporter éventuellement des back-ends et des API déployées en tant que déploiements d'API.

Dans le service API Gateway, une API désigne un ensemble de ressources back-end ainsi que les méthodes (par exemple, GET, PUT) pouvant être exécutées sur chaque ressource back-end en réponse aux demandes envoyées par un client d'API.

Pour activer une passerelle d'API afin de traiter des demandes d'API, vous devez déployer l'API sur la passerelle d'API en créant un déploiement d'API.

Pour déployer une API sur une passerelle d'API, vous avez la possibilité de créer une ressource d'API dans le service API Gateway. Une ressource d'API inclut une description d'API qui la définit. La création d'une ressource d'API est facultative. Vous pouvez déployer une API sur une passerelle d'API sans créer de ressource d'API dans le service API Gateway.

Dans le service API Gateway, un déploiement d'API désigne un moyen de déployer une API sur une passerelle d'API. Pour que la passerelle d'API puisse gérer les demandes adressées à l'API, vous devez créer un déploiement d'API.

Lorsque vous créez un déploiement d'API, vous définissez ses propriétés, y compris sa spécification de déploiement d'API. Chaque déploiement d'API comporte une spécification de déploiement d'API.

Vous pouvez déployer plusieurs API sur la même passerelle d'API. Une passerelle d'API peut donc héberger plusieurs déploiements d'API.

Dans le service API Gateway, une spécification de déploiement d'API décrit certains aspects d'un déploiement d'API.

Lorsque vous créez le déploiement d'API, vous définissez ses propriétés, y compris sa spécification de déploiement d'API. Chaque déploiement d'API comporte une spécification de déploiement d'API. Vous pouvez créer une spécification de déploiement d'API en :

• utilisant les boîtes de dialogue de la console,
• utilisant l'éditeur JSON de votre choix pour créer un fichier JSON distinct,
• utilisant une description d'API que vous avez téléchargée à partir d'un fichier de description d'API écrit dans un langage pris en charge (par exemple, OpenAPI Specification version 3.0).

Chaque spécification de déploiement d'API décrit des ressources back-end, le routage vers chacune de ces ressources et les méthodes (par exemple, GET, PUT) pouvant être exécutées sur chacune d'entre elles. La spécification de déploiement d'API décrit l'intégration de la passerelle d'API avec le back-end qui permet d'exécuter ces méthodes. La spécification de déploiement d'API peut également inclure des stratégies de demande et de réponse.

Dans le service API Gateway, vous avez la possibilité de créer une ressource d'API. Une ressource d'API est la représentation de conception d'une API. Vous pouvez utiliser une ressource d'API pour déployer une API sur une passerelle d'API.

Une description d'API définit une ressource d'API, notamment :

• les adresses disponibles,
• les opérations disponibles sur chaque adresse,
• les paramètres pouvant être entrés et sortis pour chaque opération,
• les méthodes d'authentification.

Si vous utilisez une ressource d'API pour déployer une API sur une passerelle d'API, sa description préremplit certaines des propriétés de la spécification de déploiement d'API.

Vous importez la description d'API à partir d'un fichier (parfois appelé "spécification d'API") écrit dans un langage pris en charge. Actuellement, les spécifications OpenAPI Specification version 2.0 (anciennement Swagger Specification 2.0) et version 3.0 sont prises en charge.

Vous pouvez également générer un kit SDK à partir du fichier de description d'API.

La création d'une ressource d'API dans le service API Gateway est facultative. Vous pouvez déployer une API sur une passerelle d'API sans créer de ressource d'API dans le service API Gateway. Vous pouvez également créer une ressource d'API sans description, puis ajouter une description d'API ultérieurement.

Dans le service API Gateway, un composant frontal permet de faire circuler les demandes au sein d'une passerelle d'API. Une passerelle d'API peut disposer d'un composant frontal public ou privé :

• Un composant frontal public rend les API déployées sur une passerelle d'API accessibles via une adresse IP publique.
• Un composant frontal privé rend les API déployées sur une passerelle d'API accessibles à un réseau cloud virtuel au moyen d'une adresse privée.

Dans le service API Gateway, un back-end permet à la passerelle d'acheminer les demandes vers les services back-end qui implémentent les API. Si vous ajoutez un back-end d'adresse privée à une passerelle d'API, vous autorisez la passerelle d'API à accéder au réseau cloud virtuel associé à cette adresse privée.

Vous pouvez également autoriser une passerelle d'API à accéder à d'autres services Oracle Cloud Infrastructure en tant que back-ends. Par exemple, vous pouvez autoriser une passerelle d'API à accéder à OCI Functions afin de créer et de déployer une API reposant sur une fonction sans serveur.

Un fournisseur d'API est une personne ou une équipe qui conçoit, implémente, fournit et exploite des API. Ces utilisateurs interagissent avec des interfaces telles que la console Oracle Cloud Infrastructure, le kit SDK, l'interface de ligne de commande et le fournisseur Terraform. Ils utilisent le service API Gateway pour déployer, surveiller et exploiter des API. Certaines organisations segmentent davantage le rôle de fournisseur d'API, par exemple :

• Des développeurs d'API en charge de la création des API et de leur déploiement sur les passerelles d'API.
• Gestionnaires de plans d'API, chargés de surveiller et de gérer l'utilisation des API (par exemple, en définissant des plans d'utilisation et des abonnés).
• Les gestionnaires API Gateway, en charge de l'administration des passerelles d'API, sont généralement en production.

Un consommateur d'API est une personne ou une équipe qui construit des applications et des services (clients d'API), et qui souhaite tirer parti des API proposées par un fournisseur d'API. Le consommateur d'API ne partage généralement pas de location Oracle Cloud Infrastructure avec le fournisseur d'API. Il est un client du fournisseur d'API.

Un client d'API est une application ou un appareil créé par un consommateur d'API. Le client d'API appelle l'API lors de l'exécution en envoyant des demandes à la passerelle d'API sur laquelle elle est déployée. Les clients d'API communiquent avec la passerelle d'API via HTTPS (y compris HTTP/2). Les clients d'API s'authentifient généralement auprès de l'API à l'aide d'OAuth, de l'authentification de base ou de mTLS, et peuvent utiliser un autre jeton comme une clé d'API pour la mesure et la monétisation.

Un utilisateur final est l'utilisateur d'un client d'API. Il est parfois appelé "propriétaire de ressource" dans le contexte d'autorisation. L'utilisateur final n'interagit avec une API qu'à l'aide du client d'API et n'a généralement pas conscience de l'existence de l'API elle-même. Il est un client du consommateur d'API.

Dans le service API Gateway, les gestionnaires de plans d'API peuvent gérer et surveiller l'utilisation de leurs API en définissant des ressources de plan d'utilisation et des ressources d'abonné.

Une ressource de plan d'utilisation comprend des habilitations. Chaque habilitation indique :

• Limite de débit : nombre maximal de demandes d'API autorisé par seconde.
• Quota : nombre total d'appels d'API autorisés sur une période donnée (entre une minute et un mois).
• Déploiements d'API cible. Déploiements d'API auxquels les abonnés au plan d'utilisation sont autorisés à accéder.

Vous pouvez indiquer un déploiement d'API en tant que cible dans plusieurs habilitations dans différents plans d'utilisation, mais pas dans plusieurs habilitations dans le même plan d'utilisation. Une habilitation peut inclure des déploiements d'API à partir de différentes passerelles d'API.

En tant que gestionnaire de plan d'API, les plans d'utilisation vous permettent de contrôler l'accès à l'API disponible pour vos clients (consommateurs d'API) et leurs clients d'API. Vous pouvez faire en sorte que l'accès à l'API soit soumis à des limites de tarif et à des quotas adaptés aux besoins particuliers des clients, ce qui vous permet de configurer différents niveaux d'accès pour différents clients.

Une ressource dʼabonné comprend :

• Un seul consommateur d'API.
• Noms de client et jetons de client pour identifier de manière unique les clients d'API créés par le consommateur d'API.
• Plans d'utilisation auxquels le consommateur d'API et ses clients d'API sont abonnés.

En tant que gestionnaire de plan d'API, vous pouvez créer des abonnés pour vos clients (consommateurs d'API) afin d'indiquer les plans d'utilisation qui permettent à leurs clients d'API d'accéder à vos API.

Pour qu'un déploiement d'API puisse être inclus dans un plan d'utilisation, vous devez indiquer l'emplacement du jeton client transmis dans les demandes. Une fois le déploiement d'API inclus dans un plan d'utilisation, les demandes doivent inclure le jeton client à cet emplacement afin d'accéder au déploiement d'API. Vous indiquez l'emplacement du jeton client dans une stratégie de demande de plan d'utilisation dans la spécification de déploiement d'API. (Notez que les jetons client que vous définissez dans les ressources de l'abonné sont destinés à la génération de rapports sur les plans d'utilisation uniquement, et non à l'authentification et à l'autorisation du client.)

Dans le service API Gateway, un routage désigne la mise en correspondance entre un chemin, des méthodes et un service back-end. Les routages sont définis dans les spécifications de déploiement d'API.

Le service API Gateway propose différents types de stratégie :

• Une stratégie de demande qui décrit les actions à effectuer sur la demande entrante d'un client d'API avant que celle-ci ne soit envoyée à un back-end.
• Une stratégie de réponse qui décrit les actions à effectuer sur la réponse renvoyée par un back-end avant que celle-ci ne soit envoyée à un client d'API.
• Une stratégie de journalisation qui décrit comment stocker les informations sur les demandes et réponses passant par une passerelle d'API, et les informations sur le traitement dans une passerelle d'API.

Vous pouvez utiliser des stratégies de demande et/ou des stratégies de réponse pour :

• limiter le nombre de demandes envoyées aux services back-end,
• activer la prise en charge de la spécification CORS,
• fournir l'authentification et l'autorisation,
• valider les demandes avant de les envoyer aux services back-end
• modifier les demandes entrantes et les réponses sortantes.
• rendre les déploiements d'API éligibles à l'inclusion dans les plans d'utilisation qui surveillent et gèrent l'accès des abonnés

Vous pouvez ajouter à une spécification de déploiement d'API des stratégies qui s'appliquent de façon globale à tous les routages de la spécification, ainsi que des stratégies qui s'appliquent uniquement à des routages particuliers.

Les stratégies API Gateway diffèrent des stratégies IAM, qui contrôlent l'accès aux ressources Oracle Cloud Infrastructure.