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:

No console do Google Cloud , acesse a página Apigee > Desenvolvimento de proxy > Proxies de API.

Acessar proxies de API
No painel Proxy de API, clique em + Criar.
No painel Criar um proxy, em Modelo de proxy > Modelo de especificação OpenAPI, selecione Proxy reverso (mais comum).

Navegue até o seguinte URL no navegador da Web:

https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

Clique com o botão direito do mouse no código exibido e selecione Salvar como.
Clique em Salvar para salvar o mocktarget3.0.yaml no local desejado.
No campo Especificações da OpenAPI, clique no botão Procurar.
Navegue até o arquivo mocktarget3.0.yaml e clique em Abrir.
Clique em Próxima.
A etapa Detalhes do proxy do assistente Criar proxy preenche automaticamente os campos com valores extraídos diretamente da especificação OpenAPI.

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

Campo	Descrição	Padrão
Nome do proxy	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 etapa 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 etapa 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 etapa Implantar, selecione um ou mais ambientes e clique em OK.
Clique em Criar.

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.

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