Conceitos do Serviço API Gateway

No serviço API Gateway, um gateway de API é um appliance de rede virtual em uma sub-rede regional.

Um gateway da API roteia o tráfego de entrada para serviços de back-end, incluindo APIs HTTP públicas, privadas e parceiras, bem como o OCI Functions. Cada gateway de API é um ponto final privado que você pode opcionalmente expor em um endereço IP público como um gateway de API pública:

• Um gateway de API privada só pode ser acessado por recursos na mesma rede privada (VCN) ou por recursos em outra rede privada ou on-premise pareada com essa rede privada. Um gateway de API privada tem um endereço IP privado e um nome de host gerado automaticamente no formato <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Observe que, embora o nome do host possa ser resolvido publicamente pela internet, ele é resolvido para o endereço IP privado do gateway de API. O tráfego para o endereço IP privado não é roteável pela internet pública; somente clientes dentro da VCN podem acessar o gateway de API. A resolubilidade pública de DNS de um endereço IP privado é o comportamento esperado, suportando várias configurações de rede nos ambientes OCI.
• Um gateway de API pública é acessível publicamente e pode ser acessado pela internet, desde que um gateway de internet esteja presente na VCN do gateway de API. Um gateway de API pública tem um endereço IP privado e um endereço IP público, e um nome de host gerado automaticamente no formato <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. O nome do host gerado é resolvido da internet para o endereço IP público, permitindo que clientes baseados na internet acessem o gateway de API.

Para garantir alta disponibilidade, você só pode criar gateways de API em sub-redes regionais (não sub-redes específicas do AD). Você pode criar gateways de API privada em sub-redes privadas ou públicas, mas só pode criar gateways de API pública em sub-redes públicas. O serviço API Gateway é regional em escopo e tolerante a falhas em domínios de disponibilidade (em regiões com vários ADs) e domínios de falha (em regiões com um único AD). Em várias regiões do AD, o serviço API Gateway seleciona automaticamente um domínio de disponibilidade ativo para encerrar o ponto final do gateway de API. Observe que, dependendo da origem e do destino do tráfego, o tráfego pode ser roteado entre domínios de disponibilidade. Se um domínio de disponibilidade ou domínio de falha falhar, o serviço API Gateway tratará automaticamente o failover e roteará o tráfego para um domínio de disponibilidade ou domínio de falha funcional.

Um gateway de API é vinculado a uma VNIC específica.

Você cria um gateway de API em um compartimento na sua tenancy. Cada gateway de API tem um único front end, zero ou mais back-ends e tem zero ou mais APIs implantadas nele como implantações da API.

No serviço API Gateway uma API é um conjunto de recursos de back-end e os métodos (por exemplo, GET, PUT) que podem ser executados em cada recurso de back-end em resposta a solicitações enviadas por um cliente de API.

Para ativar um gateway de API para processar solicitações de API, você deve implantar a API no gateway de API criando uma implantação de API.

Para implantar uma API em um gateway de API, você tem a opção de criar um recurso de API no serviço API Gateway. Um recurso da API inclui uma descrição da API que define o recurso da API. Observe que a criação de um recurso de API é opcional. Você pode implantar uma API em um gateway de API sem criar um recurso de API no serviço API Gateway.

No serviço API Gateway, uma implantação de API é o meio pelo qual você disponibiliza uma API em um gateway de API. Para que o gateway de API possa manipular solicitações para a API, você deve criar uma implantação de API.

Quando você cria uma implantação de API, define propriedades para a implantação de API, incluindo uma especificação de implantação de API. Cada implantação de API possui uma especificação de implantação de API.

Você pode implantar várias APIs no mesmo gateway de API, de modo que um único gateway de API possa hospedar várias implantações de API.

No serviço API Gateway, uma especificação de implantação de API descreve alguns aspectos de uma implantação de API.

Quando você cria a implantação de API, define propriedades para a implantação da API, incluindo uma especificação de implantação de API. Cada implantação de API possui uma especificação de implantação de API. Você pode criar uma especificação de implantação de API:

• usando caixas de diálogo na Console
• usando seu editor de JSON preferido para criar um arquivo JSON
• usando uma descrição de API que você carregou por upload de um arquivo de descrição de API gravado em uma linguagem suportada (por exemplo, OpenAPI Specification versão 3.0)

Cada especificação de implantação de API descreve um ou mais recursos de back-end, a rota para cada recurso de back-end e os métodos (por exemplo, GET, PUT) que podem ser executados em cada recurso. A especificação de implantação de API descreve como o gateway de API se integra com o back-end para executar esses métodos. A especificação de implantação de API também pode incluir políticas de solicitação e resposta.

No serviço API Gateway, você tem a opção de criar um recurso de API. Um recurso de API é a representação em design-time de uma API. Você pode usar um recurso de API para implantar uma API em um gateway de API.

Uma descrição da API define um recurso da API, incluindo:

• pontos finais disponíveis
• operações disponíveis em cada ponto final
• parâmetros que podem ser de entrada e saída para cada operação
• métodos de autenticação

Se você usar um recurso de API para implantar uma API em um gateway de API, sua descrição de API preencherá previamente algumas das propriedades da especificação de implantação de API.

Importe a descrição da API de um arquivo (às vezes chamado de 'especificação da API' ou 'espec da API') escrito em um idioma suportado. No momento há suporte para o OpenAPI Specification versão 2.0 (anteriormente Swagger Specification 2.0) e a versão 3.0.

Você também pode gerar um SDK com base no arquivo de descrição da API.

Observe que a criação de um recurso de API no serviço API Gateway é opcional. Você pode implantar uma API em um gateway de API sem criar um recurso de API no serviço API Gateway. Observe também que você pode criar um recurso de API que não tenha uma descrição de API inicialmente e, em seguida, adicionar uma descrição de API posteriormente.

No serviço API Gateway, um front-end é o meio pelo qual as solicitações fluem para um gateway de API. Um gateway de API pode ter um front-end público ou um front-end privado:

• Um front-end público expõe as APIs implantadas em um gateway de API por meio de um endereço IP público.
• Um front-end privado expõe as APIs implantadas em um gateway de API a uma VCN por meio de um ponto final privado.

No serviço API Gateway, um back-end é o meio pelo qual um gateway roteia solicitações para os serviços de back-end que implementam APIs. Se você adicionar um back-end de ponto final privado a um gateway de API, dará ao gateway de API acesso à VCN associada a esse ponto final privado.

Também é possível conceder a um gateway de API acesso a outros serviços do Oracle Cloud Infrastructure como back-ends. Por exemplo, você pode conceder a um gateway de API acesso ao OCI Functions, para que possa criar e implantar uma API que seja suportada por uma função sem servidor.

Um provedor de API é uma pessoa ou equipe que projeta, implementa, entrega e opera APIs. Esses usuários interagem com interfaces como a Console do Oracle Cloud Infrastructure, SDK, CLI e provedor Terraform. Eles usam o serviço API Gateway para implantar, monitorar e operar APIs. Algumas organizações segmentam ainda mais a atribuição de provedor de API, por exemplo, em:

• Desenvolvedores de API, com a responsabilidade de criar APIs e implantá-las em gateways de API.
• Gerentes de planos de API, com responsabilidade de monitorar e gerenciar o uso da API (por exemplo, definindo planos de uso e assinantes).
• Gerenciadores de Gateway de API, com a responsabilidade de administrar gateways de API, geralmente em produção.

Consumidor de API é uma pessoa ou equipe que cria aplicativos e serviços (clientes de API) e deseja aproveitar uma ou mais APIs oferecidas por um provedor de API. O consumidor da API geralmente não está compartilhando uma tenancy do Oracle Cloud Infrastructure com o provedor de API. O consumidor de API é um cliente do provedor de API.

Um cliente de API é um aplicativo ou dispositivo criado por um consumidor de API. O cliente da API chama a API no runtime enviando solicitações ao gateway de API no qual a API está implantada. Os clientes de API se comunicam com o gateway de API por HTTPS (incluindo HTTP/2). Os clientes da API geralmente se autenticam junto à API usando OAuth, Basic Auth, mTLS e podem usar algum outro token, como uma chave de API para medição e monetização.

Um usuário final é um usuário de um cliente API e às vezes é chamado de "resource-owner" (proprietário do recurso) em termos de autorização. O usuário final só interage com uma API usando o cliente da API e geralmente desconhece a própria API. O usuário final é um cliente do consumidor da API.

No serviço API Gateway, os gerentes de plano de API podem gerenciar e monitorar o uso de suas APIs definindo recursos de plano de uso e recursos de assinante.

Um recurso de plano de uso compreende direitos. Cada direito especifica:

• Um limite de taxa: O número máximo de solicitações de API permitidas por segundo.
• Uma cota: O número total de chamadas de API permitidas em um determinado período (entre um minuto e um mês).
• Uma ou mais implantações de API de destino. As implantações de API que os assinantes do plano de uso têm direito de acessar.

Você pode especificar uma implantação de API como destino em vários direitos em diferentes planos de uso, mas não em vários direitos no mesmo plano de uso. Um direito pode incluir implantações de API de diferentes gateways de API.

Como gerente de planos de API, os planos de uso permitem controlar o acesso à API disponível para seus clientes (consumidores de API) e seus clientes de API. Você pode tornar o acesso à API sujeito a limites de taxa e cotas adaptados às necessidades específicas do cliente, permitindo configurar diferentes camadas de acesso para diferentes clientes.

Um recurso de assinante compreende:

• Um único consumidor de API.
• Nomes de clientes e tokens de clientes para identificar exclusivamente clientes de API criados pelo consumidor de API.
• Planos de uso para os quais o consumidor da API e seus clientes da API estão inscritos.

Como gerente de planos de API, você pode criar assinantes para seus clientes (consumidores de API) para especificar os planos de uso que dão aos clientes de API acesso às suas APIs.

Para tornar uma implantação de API elegível para inclusão em um plano de uso, você especifica o local do token do cliente informado nas solicitações. Depois que a implantação de API tiver sido incluída em um plano de uso, as solicitações deverão incluir o token do cliente neste local para acessar a implantação de API. Você especifica o local do token do cliente em uma política de solicitação de plano de uso na especificação de implantação de API. (Observe que os tokens de cliente definidos nos recursos do assinante são apenas para fins de relatório do plano de uso e não para autenticação e autorização do cliente.)

No serviço API Gateway, uma rota é o mapeamento entre um caminho, um ou mais métodos e um serviço de back-end. As rotas são definidas nas especificações de implantação da API.

No serviço API Gateway, há diferentes tipos de política:

• uma política de solicitação descreve ações a serem executadas em uma solicitação de entrada de um cliente de API antes de ser enviada a um back-end
• uma política de resposta descreve as ações a serem executadas em uma resposta retornada de um back-end antes de ela ser enviada a um cliente de API
• uma política de log descreve como armazenar informações sobre solicitações e respostas que passam por um gateway de API e informações sobre o processamento dentro de um gateway de API

Você pode usar políticas de solicitação e/ou políticas de resposta para:

• limitar o número de solicitações enviadas a serviços de back-end
• ativar o suporte ao compartilhamento de recursos entre origens (CORS, Cross-Origin Resource Sharing)
• fornecer autenticação e autorização
• validar solicitações antes de enviá-las para serviços de back-end
• modificar solicitações de entrada e respostas de saída
• tornar as implantações de API elegíveis para inclusão em planos de uso que monitoram e gerenciam o acesso do assinante

Você pode adicionar políticas a uma especificação de implantação de API que se aplique globalmente a todas as rotas na especificação de implantação de API, bem como políticas que se apliquem somente a rotas específicas.

Observe que as políticas do serviço API Gateway são diferentes das políticas do serviço IAM, que controlam o acesso aos recursos do Oracle Cloud Infrastructure.