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

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

Confira a documentação da Apigee Edge.

O que você vai aprender

Neste tutorial, você aprenderá a:

Criar um proxy da API Apigee 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.

Você aprenderá como criar um proxy da API Apigee a partir de uma especificação OpenAPI usando a IU da Apigee. 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

"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 Open API Initiative, consulte A especificação OpenAPI.

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, consulte APIs de amostra da Apigee

Pré-requisitos

Antes de começar, é preciso concluir as etapas em Visão geral e pré-requisitos.
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 apigee/api-platform-samples (em inglês).
cURL instalado na máquina para fazer chamadas de API pela linha de comando ou um navegador da Web.

Criar o proxy de API

Para criar o proxy de API com base em uma especificação OpenAPI:

Se você estiver usando a interface da Apigee no Console do Cloud: selecione Desenvolvimento de proxy > Proxies de API.

Se você estiver usando a interface clássica da Apigee: selecione Desenvolver > proxies de API e no painel Proxies, selecione o ambiente do proxy.
Clique em API Proxies na janela principal.
Como alternativa, selecione Develop > API Proxies na barra de navegação à esquerda.
Clique em Criar nova.
No assistente de criação de proxy, clique em Use OpenAPI Spec para o modelo Reverse proxy (most common).
Clique em URL e digite as seguintes informações:
OpenAPI Spec URL: caminho para o conteúdo bruto do 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
```

Clique em Selecionar.

A página detalhes de proxy 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:

A tabela a seguir descreve os valores padrão pré-preenchidos usando a especificação OpenAPI:

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 pelo nome de domínio externo ou interno e neste caminho base. Por exemplo: `http://apitest.acme.com/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
...

Na página Detalhes do proxy, edite o campo Descrição da seguinte maneira:
```
API proxy for the Apigee mock target service endpoint.
```
Clique em Próxima.
Na página Common policies, em Security: Authorization verifique se a opção Pass through (no authorization) está selecionada e clique em Next:
Na página Fluxos, verifique se todas as operações estão selecionadas.
Dica: os fluxos condicionais são gerados automaticamente com base nas operações definidas no objeto paths na especificação OpenAPI. Os fluxos condicionais informam à Apigee o seguinte: "Ao ver isto, execute esta lógica." Por exemplo, quando uma chamada de API é GET no recurso /xml (a condição), ela transforma a resposta em JSON (por meio de uma política anexada ao fluxo condicional). Apenas um fluxo é executado por transação, o primeiro que tem uma condição avaliada como verdadeira.
Clique em Próxima.
Na página Resumo, verifique se um ambiente está selecionado em Implantação opcional e clique em Criar e implantar:

A Apigee cria seu novo proxy de API e o implanta no ambiente:
Clique em Edit proxy para exibir a página Visão geral do proxy de API.

Testar o proxy de API

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

em que YOUR_ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

Exemplo:

curl -v -k https://apitest.acme.com/myproxy

Resposta

Você verá a seguinte resposta:

Hello, Guest!

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.

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

em que YOUR ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

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.

Novo Editor de proxy

Clique na guia Develop na página visão geral da API Mock-Target na IU da Apigee.

Selecionar "View XML Response"

No painel esquerdo do navegador, em Proxy Endpoints > default, clique no fluxo condicional View XML Response.
No painel à esquerda, clique no botão + na linha Políticas.
NaCriar política clique no botãoSelecionar tipo de política campo, role para baixo atéMediação e selecioneXMLToJSON. de dados. Mantenha os valores padrão de Display Name e Name.
Clique em Criar para criar a política.
Clique no botão + ao lado do fluxo View XML response no campo Response.
Na caixa de diálogo Add Policy Step, clique no campo Select existing policy e selecione XML to JSON-1.
Clique em Add. A política XML para JSON é aplicada à resposta.

Para ver o código do fluxo condicional View XML Response, clique em Switch To Code Editor.
Clique em Save.

Editor de proxy clássico

Clique na guia Develop na página visão geral da API Mock-Target na IU da Apigee.
No painel esquerdo do navegador, em Proxy Endpoints > default, clique no fluxo condicional View XML Response.
Clique no botão +Step inferior, correspondente à Response do fluxo.

A caixa de diálogo Add Step é aberta para exibir uma lista categorizada de todas as políticas que podem ser adicionadas.
Role até a categoria Mediation e selecione XML to JSON.
Mantenha os valores padrão de Display Name e Name.
Clique em Add. A política XML para JSON é aplicada à resposta.
Clique em Save.

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 -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

em que YOUR ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

A resposta XML é convertida em JSON:

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