Conceptos de gateway de API

En el servicio de gateway de API, un gateway de API es un dispositivo de red virtual en una subred regional.

Un gateway del API direcciona el tráfico entrante a los servicios de backend, incluidas las API HTTP de partner, privadas y públicas, así como OCI Functions. Cada gateway de API es un punto final privado que, si lo desea, se puede exponer en una dirección IP pública como gateway de API pública:

• Solo pueden acceder a un gateway de API privado los recursos de la misma red privada (VCN) o los recursos de otra red privada o local que esté conectada a esa red privada. Un gateway de API privado tiene una dirección IP privada y un nombre de host generado automáticamente con el formato <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Tenga en cuenta que, aunque el nombre de host se puede resolver públicamente desde Internet, se resuelve en la dirección IP privada del gateway de API. El tráfico a la dirección IP privada no se puede enrutar desde la red pública de Internet; solo los clientes de la VCN pueden acceder al gateway de API. Se espera el comportamiento esperado de la capacidad de resolución de DNS público de una dirección IP privada, que admite varias configuraciones de red en entornos OCI.
• Un gateway de API pública es de acceso público y se puede acceder a él desde Internet, siempre que haya un gateway de Internet en la VCN del gateway de API. Un gateway de API pública tiene una dirección IP privada y una dirección IP pública, y un nombre de host generado automáticamente con el formato <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. El nombre de host generado se resuelve de Internet a la dirección IP pública, lo que permite a los clientes basados en Internet acceder al gateway de API.

Para garantizar una alta disponibilidad, solo puede crear gateways de API en subredes regionales (no en subredes específicas de dominio de disponibilidad). Puede crear gateways de API privada tanto en subredes privadas como públicas, pero solo puede crear gateways de API pública en subredes públicas. El ámbito del servicio API Gateway es regional y es tolerante a errores en todos los dominios de disponibilidad (en varias regiones de AD) y en los dominios de errores (en regiones de AD únicas). En varias regiones de AD, el servicio API Gateway selecciona automáticamente un dominio de disponibilidad activo para terminar el punto final del gateway de API. Tenga en cuenta que, en función del origen y el destino del tráfico, el tráfico se puede enrutar entre dominios de disponibilidad. Si un dominio de disponibilidad o dominio de errores falla, el servicio de gateway de API gestiona automáticamente la conmutación por error y enruta el tráfico a un dominio de disponibilidad o dominio de errores en funcionamiento.

Un gateway de API está enlazado a una VNIC específica.

Se crea un gateway de API dentro de un compartimento en su arrendamiento. Cada gateway de API tiene un único front-end, cuenta con ningún o algún backend, y posee ninguna o alguna API como despliegue.

En el servicio de gateway de API, una API es un juego de recursos de backend y los métodos (por ejemplo, GET, PUT) que se pueden realizar en cada recurso de backend como respuesta a solicitudes enviadas por un cliente de API.

Para activar un gateway a fin de procesar solicitudes de API, debe crear un despliegue de la API en el gateway.

Para desplegar una API en un gateway de API, tiene la opción de crear un recurso de API en el servicio de gateway de API. Un recurso de API incluye una descripción de la API que define el recurso de API. Tenga en cuenta que crear un recurso de API es opcional. Puede desplegar una API en un gateway de API sin crear un recurso de API en el servicio de gateway de API.

En el servicio de gateway de API, un despliegue de API es el medio por el cual se despliega una API en un gateway de API. Debe crear un despliegue de API para que el gateway pueda manejar las solicitudes de dicha API.

Al crear un despliegue de API, debe definir sus propiedades, incluida una especificación del despliegue de API. Cada despliegue de API tiene una especificación de despliegue.

Un solo gateway puede alojar varios despliegues de API.

En el servicio de gateway de API, la especificación describe algunos aspectos del despliegue de API.

Al crear el despliegue de API, debe definir sus propiedades, incluida una especificación del despliegue de API. Cada despliegue de API tiene una especificación de despliegue. Puede crear una especificación de despliegue de API:

• mediante el uso de cuadros de diálogo en la consola
• mediante el uso de su editor JSON preferido para crear un archivo JSON
• mediante una descripción de la API que haya cargado desde un archivo de descripción de la API escrito en un lenguaje soportado (por ejemplo, especificación de OpenAPI versión 3.0)

Cada especificación de despliegue de API describe uno o varios recursos de backend, la ruta a cada uno y los métodos (por ejemplo, GET, PUT) que se pueden realizar en cada recurso. La especificación de despliegue de API describe cómo se integra el gateway con el backend para ejecutar dichos métodos. La especificación de despliegue de API también puede incluir políticas de solicitud y de respuesta.

En el servicio de gateway de API tiene la opción de crear un recurso de API. Un recurso de API es la representación de tiempo de diseño de una API. Puede utilizar un recurso de API para desplegar una API en un gateway de API.

Una descripción de la API define un recurso de API, incluidos:

• puntos finales disponibles
• operaciones disponibles en cada punto final
• parámetros que pueden ser de entrada y de salida para cada operación
• métodos de autenticación

Si utiliza un recurso de API para desplegar una API en un gateway de API, su descripción de la API rellena previamente algunas de las propiedades de la especificación de despliegue de API.

Importe la descripción de la API desde un archivo (a veces llamado "especificación de API" o "espec de API") escrito en un lenguaje soportado. Actualmente, están soportadas la versión 2.0 de la especificación de OpenAPI (anteriormente la especificación de Swagger 2.0) y la versión 3.0.

También puede generar un SDK desde el archivo de descripción de API.

Tenga en cuenta que la creación de un recurso de API en el servicio de gateway de API es opcional. Puede desplegar una API en un gateway de API sin crear un recurso de API en el servicio de gateway de API. Tenga en cuenta también que puede crear un recurso de API que no tenga una descripción de la API desde el principio e incluir una descripción de la API más adelante.

En el servicio de gateway de API, un front-end es el medio por el que las solicitudes se transfieren a un gateway de API. El front-end del gateway de API puede ser público o privado:

• El front-end público expone las API desplegadas en un gateway a través de una dirección IP pública.
• El front-end privado expone las API desplegadas en un gateway en una VCN a través de un punto final privado.

En el servicio de gateway de API, un backend es el medio por el que un gateway direcciona solicitudes a los servicios de backend que implementan API. Si agrega un backend de punto final privado a un gateway de API, permite que el gateway acceda a la VCN asociada a ese punto final.

También puede otorgar a un gateway de API acceso a otros servicios de Oracle Cloud Infrastructure, como los backends. Por ejemplo, puede otorgar acceso a un gateway de API a OCI Functions, de modo que pueda crear y desplegar una API respaldada por una función sin servidor.

Un proveedor de API es una persona o un equipo que diseña, implanta, entrega y trabaja con API. Estos usuarios interactúan con interfaces como la consola, el SDK, la CLI y el proveedor de Terraform de Oracle Cloud Infrastructure. Utilizan el servicio API Gateway para desplegar, supervisar y trabajar con las API. Algunas organizaciones segmentan aún más el rol de proveedor de API, por ejemplo en:

• Desarrolladores de API, responsables de crear las API y desplegarlas en los gateways de API.
• Los gestores de planes de API, con la responsabilidad de supervisar y gestionar el uso de API (por ejemplo, mediante la definición de planes de uso y suscriptores).
• Gestores de API Gateway, responsables de administrar los gateways de API, normalmente en producción.

Un consumidor de API es una persona o un equipo que crea aplicaciones y servicios (clientes de API) y desea usar una o más API proporcionadas por un proveedor de API. Normalmente, el consumidor de API no comparte un arrendamiento de Oracle Cloud Infrastructure con el proveedor de API. El consumidor de API es un cliente del proveedor de API.

Un cliente de API es una aplicación o un dispositivo creados por un consumidor de API. El cliente de API llama a la API en tiempo de ejecución enviando solicitudes al gateway de API en el que se despliega la API. Los clientes de API se comunican con el gateway de API a través de HTTPS (incluido HTTP/2). Los clientes de API normalmente se autentican con la API mediante OAuth, Basic Auth o mTLS, y pueden utilizar algún otro token, como una clave de API para medir y monetizar.

Un usuario final es un usuario de un cliente de API y a veces se denomina "propietario de recursos" desde el punto de vista de la autorización. El usuario final solo interactúa con una API mediante el cliente de API y, por lo general, no conoce a la propia API. El usuario final es un cliente del consumidor de API.

En el servicio API Gateway, los gestores de planes de API pueden gestionar y supervisar el uso de sus API mediante la definición de recursos de plan de uso y recursos de suscriptor.

Un recurso de plan de uso consta de derechos. Cada derecho especifica:

• Límite de frecuencia: número máximo de solicitudes de API permitidas por segundo.
• Una cuota: número total de llamadas de API permitidas en un período de tiempo determinado (entre un minuto y un mes).
• Uno o más despliegues de API de destino. Los despliegues de API a los que los suscriptores del plan de uso tienen derecho de acceso.

Puede especificar un despliegue de API como destino en varios derechos en diferentes planes de uso, pero no en varios derechos en el mismo plan de uso. Un derecho puede incluir despliegues de API de diferentes gateways de API.

Como gestor de planes de API, los planes de uso le permiten controlar el acceso de API disponible para sus clientes (consumidores de API) y sus clientes de API. Puede hacer que el acceso a la API esté sujeto a límites de tarifas y cuotas adaptados a las necesidades específicas del cliente, lo que le permite configurar diferentes niveles de acceso para diferentes clientes.

Un recurso de suscriptor consta de:

• Un único consumidor de API.
• Nombres de cliente y tokens de cliente para identificar de forma única los clientes de API creados por el consumidor de API.
• Planes de uso a los que están suscritos el consumidor de API y sus clientes de API.

Como gestor de planes de API, puede crear suscriptores para sus clientes (consumidores de API) para especificar los planes de uso que otorgan a sus clientes de API acceso a sus API.

Para que un despliegue de API sea elegible para su inclusión en un plan de uso, especifique la ubicación del token de cliente transferido en las solicitudes. Una vez que el despliegue de API se ha incluido en un plan de uso, las solicitudes deben incluir el token de cliente en esta ubicación para acceder al despliegue de API. Especifique la ubicación del token de cliente en una política de solicitud del plan de uso en la especificación de despliegue de API. (Tenga en cuenta que los tokens de cliente que defina en los recursos de suscriptor son solo para fines de generación de informes del plan de uso y no para la autenticación y autorización del cliente).

En el servicio de gateway de API, una ruta es la asignación entre una ruta de acceso, uno o varios métodos y un servicio de backend. Las rutas se definen en las especificaciones de despliegue de API.

En el servicio de gateway de API, hay diferentes tipos de políticas:

• una política de solicitud que describe las acciones que se deben llevar a cabo en una solicitud entrante de un cliente de API antes de que se envíe a un backend
• una política de respuesta que describe las acciones que se deben llevar a cabo en una respuesta devuelta desde un backend antes de enviarla a un cliente de API
• una política de registro que describe cómo almacenar información sobre solicitudes y respuestas que pasan por un gateway de API e información sobre el procesamiento en un gateway de API

Puede utilizar políticas de solicitud y/o políticas de respuesta para:

• Limitar el número de solicitudes enviadas a servicios de backend.
• Activar el soporte de uso compartido de recursos de origen cruzado (CORS).
• Proporcionar autenticación y autorización.
• validar solicitudes antes de enviarlas a servicios de backend
• modificar solicitudes entrantes y respuestas salientes
• Hacer que los despliegues de API sean elegibles para su inclusión en planes de uso que supervisan y gestionan el acceso de suscriptores

Puede agregar políticas a una especificación de despliegue de API que se aplican de forma global a todas las rutas de dicha especificación, así como políticas que se aplican solo a rutas concretas.

Tenga en cuenta que las políticas de gateway de API son distintas a las políticas de IAM, que controlan el acceso a los recursos de Oracle Cloud Infrastructure.