Como criar um proxy de API simples

Você está vendo a documentação da Apigee X.
Ver 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:

Assista ao vídeo a seguir para ter uma visão geral do processo de criação de um proxy de API:

Como criar um proxy de API usando a IU

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

Para que a API ofereça suporte ao CORS, selecione Add CORS headers na página Common policies do assistente de criação de 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 Develop tab.

    Guia "Develop", menu "Save" expandido, "Save as new revision" em destaque

  5. Selecione Project > 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.