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

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:

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

2. Clique em API Proxies na janela principal.

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

   

3. Clique em Criar nova.

   

4. No assistente de criação de proxy, clique em Use OpenAPI Spec para o modelo Reverse proxy (most common).

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

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

7. Na página Detalhes do proxy, edite o campo Descrição da seguinte maneira:

   API proxy for the Apigee mock target service endpoint.

8. Clique em Próxima.
9. Na página Common policies, em Security: Authorization verifique se a opção Pass through (no authorization) está selecionada e clique em Next:

   

10. Na página Fluxos, verifique se todas as operações estão selecionadas.
11. Clique em Próxima.
12. 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:

13. Clique em Edit proxy para exibir a página Visão geral do proxy de API.

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

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

Hello, Guest!

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

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

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

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