Concepts relatifs au service de passerelle d'API

Dans le service Passerelle d'API, une passerelle d'API est un boîtier de réseau virtuel dans un sous-réseau régional.

Une passerelle d'API achemine le trafic entrant vers des services dorsaux, notamment les API HTTP publiques, privées et de partenaires ainsi qu'OCI Functions. Chaque passerelle d'API est un point d'extrémité privé, que vous pouvez facultativement exposer 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 place appairé à ce réseau privé. Une passerelle d'API privée a une adresse IP privée et un nom d'hôte généré automatiquement dans le format <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Notez que même si le nom d'hôte peut ê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 ne peut pas être routé à partir du réseau Internet public; seuls les clients du VCN peuvent accéder à la passerelle d'API. La résolvabilité DNS publique d'une adresse IP privée est un comportement attendu, qui prend 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 a à la fois une adresse IP privée et une adresse IP publique, et un nom d'hôte généré automatiquement dans le format <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Le nom d'hôte généré passe d'Internet à l'adresse IP publique, ce qui permet aux clients basés sur Internet d'accéder à la passerelle d'API.

Pour garantir la 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, mais vous pouvez seulement créer des passerelles d'API publiques dans des sous-réseaux publics. Le service API Gateway est régional pour l'ensemble des domaines de disponibilité (dans des régions comportant plusieurs domaines de disponibilité) et des domaines d'erreur (dans des régions comportant un seul domaine de disponibilité). Dans plusieurs régions AD, le service de passerelle d'API sélectionne automatiquement un domaine de disponibilité actif pour mettre fin au point d'extrémité de la passerelle d'API. Notez que, selon la source et la destination du trafic, celui-ci peut être acheminé entre les domaines de disponibilité. En cas de défaillance d'un domaine de disponibilité ou d'un domaine d'erreur, le service de passerelle d'API gère automatiquement le basculement et achemine le trafic vers un domaine de disponibilité ou d'erreur fonctionnel.

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

Vous créez une passerelle d'API dans un compartiment de votre location. Chaque passerelle d'API comprend un seul élément frontal, zéro ou plusieurs éléments dorsaux, et zéro ou plusieurs API déployées sur la passerelle en tant que déploiements d'API.

Dans le service Passerelle d'API, une API est composée d'un jeu de ressources dorsales et de méthodes (par exemple, GET, PUT) pouvant être utilisées pour chaque ressource dorsale en réponse aux demandes envoyées par un client d'API.

Pour permettre à une passerelle d'API de traiter les demandes d'API, vous devez déployer l'API cette passerelle 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 Passerelle d'API. Une ressource d'API comprend la description de l'API qui définit la ressource en question. Notez que 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 Passerelle d'API.

Dans le service Passerelle d'API, un déploiement d'API est le moyen par lequel vous déployez une API sur une passerelle d'API. Pour que la passerelle d'API puisse traiter 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 des propriétés pour le déploiement, notamment une spécification de déploiement d'API. Chaque déploiement d'API est accompagné d'une spécification de déploiement d'API.

Vous pouvez déployer plusieurs API sur la même passerelle d'API. Ainsi, une passerelle d'API peut héberger plusieurs déploiements d'API.

Dans le service Passerelle d'API, 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 des propriétés pour le déploiement, notamment une spécification de déploiement d'API. Chaque déploiement d'API est accompagné d'une spécification de déploiement d'API. Vous pouvez créer une spécification de déploiement d'API comme suit :

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

Chaque spécification de déploiement d'API décrit une ou plusieurs ressources dorsales, la route vers chacune d'entre elles et les méthodes (par exemple, GET, PUT) pouvant être utilisées pour chaque ressource. La spécification de déploiement d'API décrit comment la passerelle d'API s'intègre à l'élément dorsal pour exécuter ces méthodes. Elle peut également inclure des politiques de demande et de réponse.

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

La description de l'API définit une ressource d'API, notamment :

• Points d'extrémité disponibles
• Opérations disponibles sur chaque point d'extrémité
• Paramètres pouvant être utilisés comme entrée et sortie pour chaque opération
• Méthodes d'authentification

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

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

Vous pouvez également générer une trousse SDK à partir du fichier de description de l'API.

Notez que la création d'une ressource d'API dans le service Passerelle 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 Passerelle d'API. Notez également que vous pouvez créer une ressource d'API sans description de l'API initialement, puis ajouter la description plus tard.

Dans le service Passerelle d'API, l'élément frontal est le moyen par lequel les demandes sont transférées dans une passerelle d'API. Une passerelle d'API peut avoir un élément frontal public ou un élément frontal privé :

• Un élément frontal public expose les API déployées sur une passerelle d'API au moyen d'une adresse IP publique.
• Un élément frontal privé expose les API déployées sur une passerelle d'API dans un réseau en nuage virtuel au moyen d'un point d'extrémité privé.

Dans le service Passerelle d'API, l'élément dorsal est le moyen par lequel une passerelle achemine les demandes vers les services dorsaux qui mettent en oeuvre les API. Si vous ajoutez un élément dorsal à point d'extrémité privé à une passerelle d'API, vous accordez à la passerelle d'API l'accès au réseau en nuage virtuel associé à ce point d'extrémité privé.

Vous pouvez également accorder à une passerelle d'API l'accès à d'autres services Oracle Cloud Infrastructure en tant qu'éléments dorsaux. Par exemple, vous pouvez accorder à une passerelle d'API l'accès au service des fonctions pour OCI afin de créer et de déployer une API qui est soutenue par une fonction sans serveur.

Un fournisseur d'API est une personne ou une équipe qui conçoit, met en œuvre, livre et exploite des API. Ces utilisateurs interagissent avec des interfaces telles que la console, une trousse SDK, l'interface de ligne de commande et le fournisseur Terraform pour Oracle Cloud Infrastructure. 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 en :

• Développeurs d'API, chargés de créer des API et de les déployer sur les passerelles d'API.
• Les 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).
• Gestionnaires de passerelle d'API, chargés d'administrer les passerelles d'API, généralement en production.

Un consommateur d'API est une personne ou une équipe qui crée des applications et des services (clients d'API) et souhaite tirer parti d'une ou de plusieurs API offertes 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. Le consommateur d'API est un client du fournisseur d'API.

Un client d'API est une application ou un périphérique créé par un consommateur d'API. Le client d'API appelle l'API au moment de l'exécution en envoyant des demandes à la passerelle d'API sur laquelle l'API est déployée. Les clients d'API communiquent avec la passerelle d'API par HTTPS (y compris HTTP/2). Les clients d'API s'authentifient généralement auprès de l'API à l'aide des protocoles OAuth, d'authentification de base ou mTLS et peuvent utiliser d'autres jetons, comme une clé d'API aux fins de mesures et de monétisation.

Un utilisateur final est l'utilisateur d'un client d'API, parfois appelé "responsable de la ressource" en termes d'autorisation. L'utilisateur final interagit uniquement avec une API à l'aide du client d'API et ignore généralement l'existence de l'API elle-même. L'utilisateur final est un client du consommateur d'API.

Dans le service de passerelle d'API, 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 droits. Chaque droit précise :

• Limite de débit : Nombre maximal de demandes d'API autorisées par seconde.
• Quota : Nombre total d'appels d'API autorisés sur une période donnée (entre une minute et un mois).
• Un ou plusieurs déploiements d'API cible. Les déploiements d'API auxquels les abonnés au plan d'utilisation ont accès.

Vous pouvez spécifier un déploiement d'API comme cible dans plusieurs droits dans différents plans d'utilisation, mais pas dans plusieurs droits dans le même plan d'utilisation. Un droit peut inclure des déploiements d'API à partir de différentes passerelles d'API.

En tant que gestionnaire de plans 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 soumettre l'accès à l'API à des limites de tarifs 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 permettant d'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 plans d'API, vous pouvez créer des abonnés pour vos clients (consommateurs d'API) afin de spécifier les plans d'utilisation qui donnent à leurs clients d'API l'accès à vos API.

Pour rendre un déploiement d'API admissible à l'inclusion dans un plan d'utilisation, vous spécifiez 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 pour accéder au déploiement d'API. Vous spécifiez l'emplacement du jeton client dans une politique 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 d'abonné sont uniquement à des fins de production de rapports sur le plan d'utilisation, et non pour l'authentification et l'autorisation du client.)

Dans le service Passerelle d'API, une route est un mappage entre un chemin, une ou plusieurs méthodes et un service dorsal. Les routes sont définies dans les spécifications de déploiement d'API.

Dans le service Passerelle d'API, il existe divers types de politique :

• Une politique de demande décrit les actions à effectuer sur une demande entrante en provenance d'un client d'API avant son envoi à un élément dorsal.
• Une politique de réponse décrit les actions à effectuer sur une réponse retournée par un élément dorsal avant son envoi à un client d'API.
• Une politique de journalisation décrit le stockage des informations sur les demandes et les réponses transmises par une passerelle d'API, et des informations sur le traitement dans une passerelle d'API

Vous pouvez utiliser des politiques de demande ou de réponse pour :

• Limiter le nombre de demandes envoyées aux services dorsaux
• Prendre en charge la spécification CORS (Cross-Origin Resource Sharing)
• Assurer l'authentification et l'autorisation
• valider les demandes avant de les envoyer aux services dorsaux
• Modifier des demandes entrantes et des réponses sortantes
• rendre les déploiements d'API admissibles à l'inclusion dans les plans d'utilisation qui surveillent et gèrent l'accès des abonnés

Dans une spécification de déploiement d'API, vous pouvez ajouter des politiques qui s'appliquent globalement à toutes les routes, ainsi que des politiques qui s'appliquent uniquement à des routes particulières.

Notez que les politiques du service Passerelle d'API sont différentes des politiques GIA, qui contrôlent l'accès aux ressources Oracle Cloud Infrastructure.