Criar um proxy de API simples

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Com o Apigee Edge, você expõe 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. Basta informar o endereço de rede do serviço de back-end, além de algumas informações para a Edge criar o proxy de API que é exposto aos 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.

Assista a este vídeo 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.

Edge

Para acessar o assistente "Criar proxy" usando a IU do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Desenvolver > Proxies de API na barra de navegação à esquerda.
  3. Clique em +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", "SOAP service", "No Target" ou "Proxy bundle" para personalizar o fluxo do assistente.

Borda clássica (nuvem privada)

Para acessar o assistente "Criar proxy" usando a interface clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione APIs > Proxies de API na barra de navegação superior.
  3. Clique em + Proxy de API.

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", "SOAP service", "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.

Serviço SOAP Um proxy de API gerado com base em um arquivo WSDL. Consulte Como expor um serviço da Web baseado em SOAP como um proxy de API.
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.

Destino hospedado

Um proxy de API que roteia para um aplicativo Node.js implantado no ambiente de destinos hospedados. Consulte Visão geral de destinos hospedados.

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 descrevem como criar um proxy de API usando cada fonte.

Como criar um proxy reverso para um serviço HTTP

O Edge gera proxies reversos com base em duas 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).

Edge

  1. Acesse o assistente de criação de proxy, conforme descrito anteriormente em Como criar um proxy de API usando a IU.
  2. No assistente, clique em Reverse proxy (most common). Para gerar o proxy com base em uma especificação de OpenAPI válida, clique em Use OpenAPI Spec. Para ver detalhes sobre essa opção, consulte Como usar especificações de OpenAPI para gerar proxies abaixo.
  3. Na página Detalhes do assistente, digite as seguintes informações.
    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(s)://[host] do proxy de API. O Edge usa o URI do caminho base para corresponder e rotear mensagens de solicitação recebidas para o proxy de API adequado.

    OBSERVAÇÃO: o caminho base do proxy de API assume como padrão o valor especificado para Name convertido em letras minúsculas.

    Após o caminho base estão todos os URLs de recursos extras. Esta é a estrutura de URL completa que os clientes usarão para chamar o proxy de API:

    https://[host]/base_path/conditional_flow_path

    OBSERVAÇÃO: o caminho de base precisa ser único. não é possível implantar dois proxies de API com o mesmo caminho de base. Se você editar um proxy de API implantado e definir o caminho base com o mesmo valor que o caminho base de outro proxy de API, o Edge cancelará automaticamente a implantação do proxy de API quando ele for salvo. Antes de reimplantar o proxy de API, será preciso editar o caminho de base para que ele seja exclusivo.

    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.
  4. Na página Políticas comuns do assistente, configure o seguinte:
    • Requisitos de autorização de segurança em Security: Authorization. Consulte Como adicionar segurança mais adiante nesta seção.
    • Suporte para Compartilhamento de recursos entre origens (CORS, na sigla em inglês) em Security: Browser. Consulte Como adicionar suporte para o CORS mais adiante nesta seção.
    • Cotas para proteger 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.
    • A aplicação do limite de monetização para organizações ativadas com esse recurso ativado em Monetization. Consulte Aplicar limites de monetização em proxies de API.
  5. Na página Virtual hosts do assistente, selecione os hosts virtuais que serão vinculados ao proxy de API no momento da implantação. Para mais informações, consulte Sobre hosts virtuais.
  6. Na página Resumo, selecione os ambientes de implantação, se quiser, e clique em Criar e implantar.

    Seu novo proxy de API é criado e implantado no ambiente selecionado.

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

Borda clássica (nuvem privada)

  1. Acesse o assistente de criação de proxy, conforme descrito anteriormente em Como criar um proxy de API usando a IU.
  2. No assistente de criação de proxy, selecione Proxy reverso (mais comum). Para gerar o proxy com base em uma especificação OpenAPI válida, clique em Usar OpenAPI. Para mais detalhes sobre essa opção, consulte Como usar as especificações da OpenAPI para gerar proxies abaixo.
  3. Clique em Next.
  4. Na página Detalhes do assistente, digite as seguintes informações.
    Campo Descrição
    Nome do proxy O nome exibido para sua API.
    Caminho base de proxy

    O caminho base do proxy é um fragmento de URI depois do endereço http(s)://[host] do proxy da API. O Edge usa o URI do caminho base para corresponder e rotear mensagens de solicitação recebidas para o proxy de API adequado.

    Observação: para ver as recomendações da Apigee sobre o controle de versões da API, consulte Controle de versões no e-book Design da API da Web: a vinculação que falta.

    Depois do caminho base, há os URLs de recursos adicionais. Veja a estrutura completa do URL que os clientes usarão para chamar o proxy da API:

    https://[host]/base_path/conditional_flow_path

    Observação: o caminho base precisa ser exclusivo. Se você editar esse proxy e definir o caminho base dele para ser o mesmo de outro proxy de API, esse proxy de API será removido automaticamente quando você o salvar. É preciso editar o caminho base antes de implantá-lo novamente.

    Como usar um caractere curinga em caminhos base

    Use um ou mais caracteres curinga /*/ nos caminhos base do proxy de API para preparar os proxies para o futuro. Por exemplo, um caminho base de /team/*/members permite que os clientes chamem https://[host]/team/blue/members e https://[host]/team/green/members sem que você precise criar novos proxies de API para dar suporte a novas equipes. Não há suporte para /**/.

    Observação: o padrão do caminho base do proxy é o valor especificado no nome do proxy convertido em letras minúsculas, a menos que você edite explicitamente o conteúdo no campo "Caminho da base do proxy".

    API atual O URL que a plataforma da API invoca em nome dos apps que chamam sua API pelo URL do proxy da API.
    Descrição Descrição da API.
  5. Na página Segurança do assistente, configure o seguinte:
  6. Na página Virtual Hosts do assistente, selecione os hosts virtuais aos quais o proxy de API será vinculado quando implantado. Para mais informações, consulte Sobre hosts virtuais.
  7. Selecione os ambientes de implantação e clique em Criar e implantar
    Uma confirmação é enviada para confirmar que o novo proxy de API foi criado e implantado no ambiente selecionado.
  8. Clique em Ver o proxy de <nome do proxy> no editor para acessar a página de detalhes do proxy de API.

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 de API como um conjunto de arquivos externos ao Edge, é possível mantê-los em um sistema de controle de origem e importá-los para o Edge para testes e implantação.

Assista a este vídeo para saber como criar e importar um proxy de API de um pacote.

Edge

Para importar proxies de API de um pacote de proxy de API:

  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 Fazer upload do pacote de proxy no assistente de proxy, digite as seguintes informações.

    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.
    Será exibida uma confirmação sobre a criação do novo proxy de API.
  6. Clique em Edit proxy para exibir a página de detalhes do proxy de API.

Borda clássica (nuvem privada)

  1. Acesse o assistente de criação de proxy, conforme descrito anteriormente em Como criar um proxy de API usando a IU.
  2. No assistente "Criar um proxy", selecione Pacote de proxy.
  3. Clique em Next.
  4. Na página Details do assistente de proxy, digite as seguintes informações.

    Campo Descrição
    Pacote ZIP Clique em Escolher arquivo e navegue até o arquivo ZIP que contém a configuração do proxy da API.
    Nome do proxy O nome exibido para sua API.
  5. Revise as informações do build e clique em Build.
    Se tudo der certo, uma mensagem será exibida, e o Edge implantará automaticamente o proxy de API importado no ambiente selecionado na organização. A API exposta pelo proxy estará disponível para ser invocada.
  6. Clique em View the <proxy name> proxy no editor para mostrar a página de detalhes do proxy de API.
  7. Para implantar o proxy, clique no menu suspenso Implantação, selecione o ambiente em que você quer implantar e responda ao prompt.

Como expor um serviço da Web baseado em SOAP como um proxy de API

No assistente de criação de proxy, clique em SOAP Service e siga o assistente para criar um proxy de passagem ou REST para um serviço SOAP. Para detalhes, consulte Como expor um serviço SOAP como um proxy de API.

Como reforçar a segurança

Na página Common Policies (Edge) ou Security (Edge clássico) 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. O Apigee Edge adiciona automaticamente duas 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 verificações de segurança no Apigee Edge.

Como adicionar suporte para o CORS

O Compartilhamento de recursos entre origens (CORS, na sigla em inglês) é um mecanismo padrão que permite que um navegador da Web faça solicitações diretas a 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 (Edge) ou Security (Edge clássico) 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 usar especificações de OpenAPI para gerar proxies

Nesta seção, você verá como usar a OpenAPI disponível para gerar os seguintes tipos de proxies: reverso, Node.js ou sem destino.

O que é uma especificação de OpenAPI?

Logotipo da Open API Initiative"A Open API Initiative (OAI) tem como foco a criação, a evolução e a promoção de um formato de descrição de APIs sem fornecedor com base na especificação Swagger". Para mais informações sobre a Open API Initiative, consulte https://openapis.org.

Uma especificação de 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 alguns elementos de uma API, como caminho de 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.

Veja um fragmento de uma especificação de OpenAPI que descreve o serviço de destino simulado da Apigee, http://mocktarget.apigee.net. Para mais informações, consulte https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi.

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 do Edge para desenvolvê-lo ainda mais adicionando políticas, implementando código personalizado e assim por diante, assim como qualquer proxy do Edge.

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 de OpenAPI. Para detalhes, consulte Criar um proxy de API com base em uma especificação de OpenAPI.

Assista a este vídeo para saber como criar um proxy de API com base em uma especificação de OpenAPI.

Como atualizar os fluxos em um proxy de API usando uma especificação de OpenAPI

Depois de criar um proxy de API com base em uma especificação OpenAPI, se você modificá-la para adicionar outros caminhos de recursos, use a especificação para adicionar os fluxos condicionais associados ao proxy de API.

Para atualizar os fluxos em um proxy de API usando uma especificação de OpenAPI, siga estas etapas:

  1. Adicione os novos caminhos de recursos à especificação de OpenAPI. Consulte Como editar uma especificação de OpenAPI.
  2. Abra o proxy de API na IU e clique na guia Develop.
  3. No navegador, clique em + ao lado do endpoint do proxy que você quer atualizar.
    A caixa de diálogo "New Conditional Flow" será aberta.
  4. Clique em From OpenAPI se essa opção ainda não estiver selecionada.
    Se houver recursos na especificação de OpenAPI que não tenham um fluxo condicional correspondente no proxy da API, eles serão listados na caixa de diálogo, conforme mostrado na figura a seguir. Recursos que não são representados como fluxos no proxy de API atual. Este exemplo inclui /loveapis, /ip, /json e /xml.
  5. Selecione cada um dos recursos para adicionar um fluxo condicional.
  6. Clique em Adicionar.

Os fluxos condicionais são adicionados ao proxy da API.

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

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

Edge

Para criar uma nova revisão de um proxy de API usando a interface do usuário do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Develop > API Proxies na barra de navegação à esquerda.
  3. Clique no proxy de API na lista que você quer copiar.
  4. Selecione Project > Save as New Revision.

Borda clássica (nuvem privada)

Para criar uma nova revisão de um proxy de API usando a interface clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione APIs > Proxies de API na barra de navegação superior.
  3. Clique no proxy de API na lista que você quer copiar.
  4. Selecione Project > Save as New Revision.

Como copiar um proxy de API

Copie um proxy de API para um novo proxy, conforme descrito abaixo.

Edge

Para copiar um proxy de API usando a interface do usuário do Edge:

  1. Faça login em apigee.com/edge.
  2. Selecione Develop > API Proxies na barra de navegação à esquerda.
  3. Clique no proxy de API na lista que você quer copiar.
  4. Selecione Project > Save as New API Proxy.
  5. Na caixa de diálogo "Save as New Proxy", insira o nome do novo proxy de API.
  6. Clique em Adicionar.

Borda clássica (nuvem privada)

Para copiar um proxy de API usando a interface clássica do Edge:

  1. Faça login em http://ms-ip:9000, em que ms-ip é o endereço IP ou o nome DNS do nó do servidor de gerenciamento.
  2. Selecione APIs > Proxies de API na barra de navegação superior.
  3. Clique no proxy de API na lista que você quer copiar.
  4. Selecione Project > Save as New API Proxy.
  5. Na caixa de diálogo "Save as New Proxy", insira o nome do novo proxy de API.
  6. Clique em Adicionar.

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 API de proxies de API.