Criar um proxy de API com base em uma especificação OpenAPI

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

O que você vai aprender

Neste tutorial, você aprenderá a:

  • Criar um proxy da API Edge com base em uma especificação OpenAPI.
  • Chamar o proxy de API usando cURL.
  • Adicionar uma política a um fluxo condicional.
  • Testar a invocação da política usando cURL.

Neste tutorial, você aprenderá a criar um proxy da API Edge com base em uma especificação OpenAPI usando a IU de gerenciamento do Apigee Edge. Quando você chama o proxy de API com um cliente HTTP, como cURL, o proxy de API envia a solicitação para o serviço de destino simulado da Apigee.

Sobre a Iniciativa de API aberta

Iniciativa de API aberta
"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 sobre a Iniciativa de API aberta, consulte https://openapis.org.

Uma especificação OpenAPI usa um formato padrão para descrever uma API RESTful. Escrita em formato JSON ou YAML, uma especificação OpenAPI é legível por máquina, mas também é fácil de ler e entender por pessoas. A especificação descreve esses elementos de uma API como 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 OpenAPI é comumente usada para gerar a documentação da API.

Sobre o serviço de destino simulado da Apigee

O serviço de destino simulado da Apigee usado neste tutorial está hospedado na Apigee e retorna dados simples. Ele não requer nenhuma chave de API nem um token de acesso. Na verdade, é possível acessá-lo em um navegador da Web. Para testar, clique no seguinte:

http://mocktarget.apigee.net

O serviço de destino retorna a saudação Hello, guest!

Para informações sobre o conjunto completo de APIs compatíveis com o serviço de destino simulado, clique no seguinte:

http://mocktarget.apigee.net/help

Pré-requisitos

  • Uma conta do Apigee Edge. Caso não tenha uma conta, siga as instruções descritas em Como criar uma conta do Apigee Edge para se inscrever.
  • Uma especificação OpenAPI. Neste tutorial, você usará a especificação OpenAPI mocktarget.yaml, 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.
  • cURL instalado na máquina para fazer chamadas de API pela linha de comando ou um navegador da Web.

Criar o proxy de API

Edge

Para criar o proxy de API com base em uma especificação OpenAPI usando a interface do usuário do Edge:

  1. Faça login em https://apigee.com/edge.
  2. Clique em "API Proxies" na janela principal.

    Como alternativa, selecione Desenvolver > Proxies de API na barra de navegação à esquerda.

    Clicar na página de destino "API Proxies"

  3. Clique em + Proxy.
    Adicionar o proxy de API
  4. No assistente Criar proxy, clique em Usar OpenAPI Spec para o modelo Reverse proxy (most common).
    Criar um tipo de proxy
  5. Clique em Importar do URL e insira as seguintes informações:
    • URL de especificação OpenAPI: caminho para o conteúdo bruto no GitHub para a especificação OpenAPI no campo URL: 
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • Spec name: nome da especificação OpenAPI, como Mock Target.

      Esse nome é usado para armazenar a especificação OpenAPI no armazenamento de especificações. Consulte Gerenciar suas especificações.

  6. Clique em Importar.

    A página "Details" do assistente de criação de proxy é exibida. Os campos são preenchidos previamente usando os valores definidos na especificação OpenAPI, conforme mostrado a seguir:

    A tabela a seguir descreve os valores padrão já preenchidos usando as propriedades na especificação OpenAPI. Um trecho da especificação OpenAPI que ilustra as propriedades usadas é mostrado após a tabela.

    Campo Descrição Padrão
    Nome Nome do proxy de API. Por exemplo, Mock-Target-API. Propriedade title da especificação OpenAPI com espaços substituídos por traços
    Caminho base Componente de caminho que identifica exclusivamente esse proxy de API na organização. O URL público desse proxy de API é composto do nome da organização, de um ambiente onde esse proxy de API é implantado e desse caminho base. Por exemplo: http://myorg-test.apigee.net/mock-target-api Campo Nome convertido em letras minúsculas
    Descrição Descrição do proxy de API. Propriedade description da especificação OpenAPI
    Destino (API existente) URL de destino invocado em nome deste proxy de API. Qualquer URL acessível por meio da Internet aberta pode ser usado. Por exemplo: http://mocktarget.apigee.net Propriedade servers da especificação OpenAPI

    Veja a seguir um trecho da especificação OpenAPI mostrando as propriedades usadas para preencher previamente os campos.

    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
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  7. Edite o campo Description da seguinte maneira: API proxy for the Apigee mock target service endpoint.
  8. Clique em Next.
  9. Na página Políticas comuns, em "Segurança: autorização", verifique se Passar (sem autorização) está selecionado e clique em Próximo:

    Pass through (no authorization) selecionado na página "Common policies"

  10. Na página "Fluxos", verifique se todas as operações estão selecionadas. Criar fluxos de proxy
  11. Clique em Next.
  12. Na página Virtual Hosts, selecione default e secure e clique em Next.
    default e secure selecionados na página de hosts virtuais
  13. Na página Resumo, verifique se o ambiente de Teste está selecionado em Implantação opcional e clique em Criar e implantar:

    A Apigee cria o novo proxy de API e o implanta no ambiente de teste:

  14. Clique em Editar proxy para exibir a página de visão geral do proxy de API.
    Resumo do proxy da API Mock Target

Borda clássica (nuvem privada)

Para criar o proxy de API com base em uma especificação OpenAPI usando a interface clássica do Edge:

  1. Faça login em https://apigee.com/edge.
  2. Clique em "API Proxies" na janela principal.

    Como alternativa, selecione Desenvolver > Proxies de API na barra de navegação à esquerda.

  3. Clique em + Proxy.
    Adicionar o proxy de API
  4. No assistente de criação de proxy, selecione Reverse proxy (most common) e clique em Usar OpenAPI.
    Criar um tipo de proxy
  5. Clique em Importar de um URL, digite um nome para a especificação OpenAPI e informe o caminho do conteúdo bruto no GitHub para a especificação OpenAPI no campo URL:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. Clique em Selecionar.
  7. Clique em Next.

    A página "Details" do assistente de criação de proxy é exibida. Os campos são pré-preenchidos com valores definidos na especificação OpenAPI, conforme mostrado na figura a seguir.

    Detalhes de criação de um proxy

    A tabela a seguir descreve os valores padrão já preenchidos usando as propriedades na especificação OpenAPI. Um trecho da especificação OpenAPI que ilustra as propriedades usadas é mostrado após a tabela.

    Campo Descrição Padrão
    Proxy Name Nome do proxy de API. Por exemplo, Mock-Target-API. Propriedade title da especificação OpenAPI com espaços substituídos por traços
    Caminho base do proxy Componente de caminho que identifica exclusivamente esse proxy de API na organização. O URL público desse proxy de API é composto do nome da organização, de um ambiente onde esse proxy de API é implantado e desse caminho base. Por exemplo: http://myorg-test.apigee.net/mock-target-api Campo Nome convertido em letras minúsculas
    Existing API URL de destino invocado em nome deste proxy de API. Qualquer URL acessível por meio da Internet aberta pode ser usado. Por exemplo: http://mocktarget.apigee.net Propriedade servers da especificação OpenAPI
    Descrição Descrição do proxy de API. Propriedade description da especificação OpenAPI

    Veja a seguir um trecho da especificação OpenAPI mostrando as propriedades usadas para preencher previamente os campos.

    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
...
servers:
  - url: http://mocktarget.apigee.net
  - url: https://mocktarget.apigee.net
...
  8. Edite o campo Description da seguinte maneira: API proxy for the Apigee mock target service endpoint.
  9. Clique em Next.
  10. Na página "Fluxos", verifique se todas as operações estão selecionadas. Criar fluxos de proxy
  11. Clique em Next.
  12. Na página "Segurança", selecione Passar (nenhum) como a opção de segurança e clique em Avançar.
  13. Na página "Virtual Hosts", verifique se todos os hosts virtuais estão selecionados e clique em Next.
  14. Na página "Versão", verifique se o ambiente test está selecionado e clique em Build and Deploy.
  15. Na página "Resumo", você vê uma confirmação de que o novo proxy de API foi criado e implantado no ambiente de teste.
    Criar um resumo de proxy
  16. Clique em Mock-Target-API para exibir a página de visão geral do proxy de API.
    Resumo do proxy da API Mock Target

Parabéns! Você criou um proxy de API com base em uma especificação OpenAPI. Em seguida, você o testará para ver como ele funciona.

Testar o proxy de API

É possível testar sua API Mock-Target-API usando cURL ou um navegador da Web.

Em uma janela de terminal, execute o comando cURL a seguir. Substitua o nome da sua organização no URL.

curl http://<org_name>-test.apigee.net/mock-target-api

Resposta

Você verá a seguinte resposta:

Hello, Guest!

Muito bem! Você criou um proxy de API simples com base em uma especificação OpenAPI e o testou.

Adicionar uma política XML para JSON

Em seguida, adicione a política XML para JSON ao fluxo condicional View XML Response gerado automaticamente quando você criou o proxy de API com base na especificação OpenAPI. A política converterá a resposta XML do destino em uma resposta JSON.

Primeiro, chame a API para comparar os resultados com aqueles recebidos depois de adicionar a política. Em uma janela de terminal, execute o comando cURL a seguir. Você está chamando o recurso /xml do serviço de destino, que retorna nativamente um bloco simples de XML. Substitua o nome da sua organização no URL.

curl http://<org_name>-test.apigee.net/mock-target-api/xml

Resposta

Você verá a seguinte resposta:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

Agora, vamos fazer algo para converter a resposta XML em JSON. Adicione a política XML para JSON ao fluxo condicional "View XML Response" no proxy de API.

  1. Clique na guia Develop no canto superior direito da página de visão geral da Mock-Target-API na interface do Edge.
    Guia do desenvolvedor
  2. No painel esquerdo do Navigator, em "Proxy Endpoints > default", clique no fluxo condicional View XML Response.
    Selecionar &quot;View XML Response&quot;
  3. Clique no botão +Step inferior, correspondente à Response do fluxo.
    Selecionar +Step
    A caixa de diálogo "Add Step" é aberta para exibir uma lista categorizada de todas as políticas que podem ser adicionadas.
  4. Role até a categoria "Mediação" e selecione XML para JSON.
    Caixa de diálogo &quot;Add Step&quot;
  5. Mantenha os valores padrão de Display Name e Name.
  6. Clique em Adicionar. A política XML para JSON é aplicada à resposta.Política XML para JSON no fluxo
  7. Clique em Salvar.

Agora que você adicionou a política, chame novamente a API usando cURL. Observe que você ainda está chamando o mesmo recurso /xml. O serviço de destino ainda retorna o bloco de XML, mas agora a política no proxy de API converterá a resposta em JSON. Faça esta chamada:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

A resposta XML é convertida em JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

Parabéns! Você testou com sucesso a execução de uma política adicionada a um fluxo condicional.