Como criar um proxy de API simples

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A Apigee permite que você exponha rapidamente os serviços de back-end como APIs. Para isso, você precisa criar um proxy de API que forneça uma fachada para o serviço de back-end a ser exposto. É necessário fornecer apenas o endereço de rede do serviço de back-end, junto com algumas informações que a Apigee usa para criar o proxy de API que é exposto a desenvolvedores.

O proxy de API separa a implementação do serviço de back-end da API que os desenvolvedores consomem. Assim, eles se protegem das mudanças futuras nos seus serviços de back-end. Enquanto você atualiza os serviços de back-end, os desenvolvedores, isolados dessas mudanças, podem continuar chamando a API sem interrupções.

Neste tópico, você encontra informações sobre os vários tipos de proxies e as configurações para eles. Para instruções passo a passo sobre como criar proxies, consulte os seguintes tópicos:

Como criar um proxy de API usando a interface

A maneira mais fácil de criar um proxy de API é usando o assistente de criação de proxy.

Para acessar o assistente de criação de proxy usando a IU da Apigee, siga estas etapas:

  1. Faça login na IU da Apigee.
  2. Na barra de navegação, selecione Develop > API Proxies.
  3. Clique em Criar nova.
    Botão "Criar proxy"

O assistente de criação proxy exibe e direciona você pelas etapas para gerar e adicionar recursos mínimos a um proxy de API.

Primeira página do assistente de criação de proxy
    solicitando que você selecione Reverse proxy, No Target ou Proxy bundle para personalizar o fluxo do assistente.

A primeira página do assistente permite a criação de um proxy de API a com base nas seguintes origens:

Tipo Descrição
Proxy reverso (mais comum)

Um proxy de API que encaminha solicitações de entrada para os serviços de back-end HTTP. Pode ser uma API JSON ou XML. Consulte Como criar um proxy reverso para um serviço HTTP mais adiante nesta seção.

Clique em Use OpenAPI Spec para gerar o proxy com base em uma especificação de OpenAPI válida. Para mais informações sobre essa opção, consulte Como usar especificações da OpenAPI para gerar proxies mais adiante nesta seção.

Nenhum destino

Um proxy de API sem back-end de API ("sem destino"). Semelhante à criação de um proxy reverso para um serviço HTTP descrito anteriormente, exceto que você não especificará uma API ao definir os detalhes do proxy.

Clique em Use OpenAPI Spec para gerar o proxy com base em uma especificação de OpenAPI válida. Para mais informações sobre essa opção, consulte Como usar especificações da OpenAPI para gerar proxies mais adiante nesta seção.

Upload do pacote de proxy Um pacote de proxy de API. Por exemplo, um dos proxys de API de amostra disponíveis no GitHub. Consulte Como importar um proxy de API de um pacote.

As seções a seguir discutem os detalhes de cada tipo de proxy.

Como criar um proxy reverso para um serviço HTTP

A Apigee gera proxies reversos com base nestas informações:

  • URL do serviço de back-end
  • Caminho de URI que identifica exclusivamente a API que será exposta pelo proxy a apps para o consumidor

O URL do serviço de back-end normalmente representa um aplicativo ativado pelo serviço que pertence à organização. Ele também pode apontar para uma API disponível publicamente. A API ou o serviço pode estar sob seu controle (por exemplo, um aplicativo de RH interno ou um aplicativo do Rails na nuvem) ou pode ser uma API ou um serviço de terceiros (por exemplo, Twitter ou Instagram).

Os seguintes detalhes do proxy estão disponíveis depois de acessar o Criar assistente de proxy e selecionar um tipo de proxy:

Campo Descrição
Nome Nome exibido para a API. Especifique caracteres alfanuméricos, traço (-) ou sublinhado (_).
Base path

Fragmento de URI que aparece após o endereço http://[host] ou https://[host] do proxy de API. A Apigee usa o URI do caminho base para corresponder e encaminhar as mensagens de solicitação recebidas para o proxy da API adequado.

O caminho base a seguir é qualquer URL de recurso adicional. Veja a seguir a estrutura completa do URL que os clientes usam para chamar o proxy da API:

https://[host]/BASE_PATH/CONDITIONAL_FLOW_PATH

Usar caracteres curinga em caminhos de base

Use um ou mais caracteres curinga /*/ nos caminhos de base do proxy de API para preparar seus proxies para o futuro. Por exemplo, um caminho de base /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem a necessidade de criar novos proxies de API para oferecer suporte a novas equipes. /**/ não é compatível.

Descrição (Opcional) Descrição da API.
Target (Existing API) URL do serviço de back-end que este proxy de API invoca.

Como importar um proxy de API de um pacote

Muitas vezes, você define proxies de API como um conjunto de arquivos XML, além de outros arquivos de suporte. Ao definir os proxies da API como um conjunto de arquivos externos à Apigee, é possível mantê-los em um sistema de controle de origem e importá-los para a Apigee para teste e implantação.

Para importar proxies de API de um pacote de proxy de API, execute as seguintes etapas:

  1. Acesse o assistente de criação de proxy, conforme descrito anteriormente em Como criar um proxy de API usando a IU.
  2. Clique em Upload proxy bundle.
  3. Na página Upload proxy bundle no assistente de proxy, digite as informações a seguir.

    Campo Descrição
    ZIP bundle ZIP que contém a configuração do proxy de API. Arraste e solte ou clique para navegar até o arquivo.
    Nome Nome exibido para a API. O padrão é o nome do arquivo ZIP sem a extensão.
  4. Clique em Próxima.
  5. Na página Summary, selecione os ambientes de implantação, se quiser, e clique em Create and deploy.

    Uma confirmação é exibida atestar que o novo proxy da API foi criado.

  6. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Como criar proxies de API gRPC

Além dos proxies de API REST, a Apigee é atualmente compatível com proxies de API gRPC apenas com suporte de passagem. Em Suporte de passagem, o payload de gRPC é opaco para a Apigee e o tráfego é roteado do cliente de gRPC para o servidor de destino gRPC pré-configurado na configuração de destino.

No momento, os proxies de API gRPC da Apigee:

  • Oferecem suporte a solicitações de gRPC unárias.
  • Não são capazes de usar políticas que afetem o payload.
  • Pode ser usado em produtos de API que não estão associados a proxies GraphQL ou REST. As cotas específicas de produto da API e outras configurações de operação se aplicam a todos os proxies no produto.
  • Não são compatíveis com a Apigee híbrida.
  • Usam duas variáveis de fluxo específicas de gRPC: request.grpc.rpc.name e request.grpc.service.name.
  • Podem ser monitorados com estas variáveis de análise da Apigee: x_apigee_grpc_rpc_name, x_apigee_grpc_service_name e x_apigee_grpc_status.
  • Retornam os códigos de status de gRPC.

Você também precisa configurar o balanceador de carga para oferecer suporte a gRPC. Consulte Como usar gRPC com seus aplicativos e Como usar comandos da CLI gcloud para criar roteamento para gRPC.

Para criar um proxy de API gRPC, primeiro defina um servidor de destino gRPC (consulte Como criar servidores de destino) e, em seguida, especifique esse servidor de destino criando o novo proxy.

Como usar comandos da CLI gcloud para criar um roteamento para gRPC

Nesta seção, você verá exemplos de comandos para criar roteamento de proxies gRPC usando a CLI gcloud. As instruções incluem a configuração de balanceadores de carga, um servidor de destino e um MIG.

Esta seção não constitui um guia abrangente para a criação de roteamento. Os exemplos apresentados talvez não sejam apropriados para todos os casos de uso. Além disso, para seguir estas instruções, é preciso ter familiaridade com o Roteamento externo (MIG, na sigla em inglês) e a Configuração do gRPC do balanceador de carga do Cloud.

Definir as variáveis de ambiente

Essas variáveis de ambiente são usadas nos comandos das subseções.

PROJECT_ID=YOUR_PROJECT_ID
MIG_NAME=YOUR_MIG_NAME
VPC_NAME=default
VPC_SUBNET=default
REGION=REGION_NAME
APIGEE_ENDPOINT=ENDPOINT
CERTIFICATE_NAME=CERTIFICATE_NAME
DOMAIN_HOSTNAME=DOMAIN_HOSTNAME

Como reforçar a segurança

Na página Common Policies do assistente de criação de proxy, selecione o tipo de autorização de segurança que você quer adicionar. A tabela a seguir resume as opções disponíveis:

Autorização de segurança Descrição
Chave de API Adiciona uma verificação de chave de API simples ao proxy que você está definindo. Em resposta, a plataforma de API adiciona as políticas VerifyAPIKey e AssignMessage ao proxy. A política VerifyAPIKey valida as chaves de API apresentadas pelos apps que fazem as solicitações. A política AssignMessage remove a chave de API, fornecida na chamada de API como um parâmetro de consulta, da solicitação encaminhada para o servidor de back-end.
OAuth 2.0 Adiciona a autenticação baseada em OAuth 2.0 ao proxy de API. A Apigee adiciona automaticamente as seguintes políticas ao proxy de API: uma para verificar um token de acesso e outra para remover esse token da mensagem antes de encaminhá-lo para o serviço de back-end. Para saber como conseguir um token de acesso, consulte OAuth.
Passagem (sem autorização) Nenhuma autorização necessária. As solicitações são transmitidas para o back-end sem nenhuma verificação de segurança na Apigee.

Como adicionar suporte para o CORS

O compartilhamento de recursos entre origens (CORS) é um mecanismo padrão que permite ao navegador da Web fazer solicitações diretas para outro domínio. O padrão CORS define um conjunto de cabeçalhos HTTP que os servidores e os navegadores da Web usam para implementar a comunicação entre domínios.

É possível adicionar suporte ao CORS seguindo um destes procedimentos:

  • Como adicionar a política de CORS ao PreFlow de solicitação do ProxyEndpoint
  • Selecione Adicionar cabeçalhos CORS na página Políticas comuns do assistente Criar proxy

Para informações mais detalhadas sobre o suporte ao CORS, incluindo como adicionar a um proxy o suporte à simulação do CORS, consulte Como adicionar suporte para o CORS a um proxy de API.

Como adicionar cotas

Cotas protegem seu serviço de back-end contra tráfego alto em Quota. Veja Cotas. Essa opção não estará disponível se a autorização de passagem estiver selecionada.

Como usar especificações de OpenAPI para gerar proxies

Esta seção aborda a opção "Usar OpenAPI" que está disponível para geração de uma especificação OpenAPI nos tipos de proxies de API a seguir: reverso ou sem destino.

O que é uma especificação de OpenAPI?

Logotipo da Open API Initiative   "A Iniciativa de API aberta (OAI, na sigla em inglês) tem como foco criar, evoluir e promover um formato de descrição de API neutra de fornecedor com base na especificação Swagger." Para mais informações, consulte a Iniciativa OpenAPI.

Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Gravada em formato JSON ou YAML, uma especificação de OpenAPI pode ser lida por máquinas, mas também é fácil de ler e entender para nós, humanos. A especificação descreve elementos da API, como o caminho base, caminhos e verbos, cabeçalhos, parâmetros de consulta, operações, tipos de conteúdo, descrições de resposta e muito mais. Além disso, uma especificação de OpenAPI é comumente usada para gerar a documentação da API.

O fragmento a seguir de uma especificação OpenAPI descreve o serviço de destino simulado da Apigee, http://mocktarget.apigee.net (em inglês). Para mais informações, consulte Especificação OpenAPI para a amostra helloworld.

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
...

Com o assistente de criação de proxy, é possível importar uma especificação de OpenAPI e usá-la para gerar um proxy de API. Depois que o proxy for gerado, será possível usar a IU da Apigee para desenvolvê-lo ainda mais ao adicionar políticas, implementar código personalizado etc., assim como qualquer proxy da Apigee.

Como criar um proxy de API de uma especificação da OpenAPI

Crie proxies de API com base em uma especificação de OpenAPI. Com apenas alguns cliques, você terá um proxy de API com os caminhos, parâmetros, fluxos condicionais e endpoints de destino gerados automaticamente. Em seguida, será possível adicionar recursos como segurança OAuth, limitação de taxa e armazenamento em cache.

No assistente de criação de proxy, clique em Use OpenAPI Spec e siga o assistente para criar um proxy reverso ou sem destino com base em uma especificação da OpenAPI. Para detalhes, consulte Criar um proxy de API com base em uma especificação de OpenAPI.

Como criar uma nova revisão de um proxy de API

Crie uma nova revisão de um proxy de API, conforme descrito abaixo.

Para criar uma nova revisão de um proxy de API, execute as seguintes etapas:

  1. Faça login na IU da Apigee.
  2. Na barra de navegação, selecione Develop > API Proxies.
  3. Clique no proxy de API na lista que você quer copiar.
  4. Clique na guia Desenvolver.

  5. Selecione o botão Save e selecione Save as New Revision.

Como fazer backup de um proxy de API

É possível fazer backup de um proxy de API como um conjunto de arquivos XML em um pacote. Depois de exportar para um pacote, é possível importar o proxy de API para um novo proxy, conforme descrito em Como importar um proxy de API de um pacote anteriormente nesta seção. Para mais informações, consulte Fazer o download de proxies de API.

Como criar um proxy usando a API

Para criar um proxy de API usando a API, consulte Como criar um proxy de API.