Tutorial: Criar uma API REST com integração de proxy HTTP

A integração de proxy HTTP é um mecanismo simples, eficiente e versátil para criar uma API que permite que um aplicativo web acesse vários recursos ou características do endpoint HTTP integrado, por exemplo, todo o site, com a configuração simplificada de um único método da API. Na integração de proxy HTTP, o API Gateway transmite a solicitação de método enviada pelo cliente para o backend. Os dados da solicitação que são transmitidos incluem os cabeçalhos da solicitação, parâmetros da string de consulta, variáveis do caminho do URL e carga. O endpoint HTTP do backend ou o servidor web analisará os dados da solicitação recebida para determinar a resposta que ele retorna. A integração de proxy HTTP faz com que o cliente e o backend interajam diretamente sem qualquer intervenção do API Gateway após a configuração do método da API, exceto problemas conhecidos, como caracteres incompatíveis, que estão listados em Notas importantes do Amazon API Gateway.

Com o recurso de proxy totalmente abrangente {proxy+}e o verbo global ANY para o método HTTP, é possível usar uma integração de proxy HTTP para criar uma API de um único método de API. O método expõe o conjunto completo de recursos HTTP de acesso público e operações de um site. Quando o servidor web de backend abre mais recursos para o acesso público, o cliente pode usar esses novos recursos com a mesma configuração de API. Para habilitar isso, o desenvolvedor do site deve comunicar claramente ao desenvolvedor cliente quais são os novos recursos e quais operações são aplicáveis a cada um deles.

Como uma rápida introdução, o tutorial a seguir demonstra a integração de proxy HTTP. No tutorial, criamos uma API usando o console do API Gateway para integração com o site PetStore por meio de um recurso de proxy genérico {proxy+} e criamos o espaço reservado do método HTTP de ANY.

Criar uma API com integração de proxy HTTP usando o console do API Gateway

O procedimento a seguir descreve as etapas para criar e testar uma API com um recurso de proxy para um backend HTTP usando o console do API Gateway. O backend HTTP é o site PetStore (http://petstore-demo-endpoint.execute-api.com/petstore/pets) de Tutorial: Criar uma API REST com integração não proxy HTTP, no qual capturas de tela são usadas como auxílios visuais para ilustrar os elementos da IU do API Gateway. Se você ainda não sabe usar o console do API Gateway para criar uma API, talvez precise consultar essa seção primeiro.

Como criar uma API

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Se esta for a primeira vez que você usa o API Gateway, você verá uma página com os recursos do serviço. Em REST API, escolha Build (Criar). Quando o pop-up Create Example API (Criar API de exemplo) for exibido, escolha OK.

   Se essa não for a primeira vez que você usa o API Gateway, escolha Create API (Criar API). Em REST API, escolha Build (Criar).

3. Em API name (Nome da API), insira HTTPProxyAPI.

4. (Opcional) Em Description (Descrição), insira uma descrição.

5. Mantenha Tipo de endpoint da API definido como Regional.

6. Selecione Criar API.

Nesta etapa, você vai criar um caminho de recurso de proxy de {proxy+}. Esse é o espaço reservado de qualquer um dos endpoints de back-end em http://petstore-demo-endpoint.execute-api.com/. Por exemplo, ele pode ser petstore, petstore/pets e petstore/pets/{petId}. O API Gateway cria o método ANY quando você cria o recurso {proxy+} e serve como um espaço reservado para qualquer um dos verbos HTTP compatíveis em runtime.

Como criar um recurso /{proxy+}

1. Selecione a API.

2. No painel de navegação principal, selecione Recursos.

3. Selecione Criar recurso.

4. Ative Recurso proxy.

5. Mantenha Caminho do recurso como /.

6. Em Resource Name (Nome do recurso), insira {proxy+}.

7. Mantenha CORS (Compartilhamento de recursos de origem cruzada) desativado.

8. Selecione Criar recurso.

   

Nesta etapa, você vai integrar o método ANY a um endpoint HTTP de back-end usando uma integração de proxy. Na integração de proxy, o API Gateway transmite a solicitação de método enviada pelo cliente ao back-end, sem intervenção do API Gateway.

Como criar um método ANY

1. Selecione o recurso/{proxy+}.

2. Selecione o método ANY.

3. Sob o símbolo de aviso, selecione Editar integração. Não é possível implantar uma API que tenha um método sem uma integração.

4. Em Tipo de integração, selecione HTTP.

5. Ative Integração de proxy HTTP.

6. Em Método HTTP, selecione ANY.

7. Em URL do endpoint, insira http://petstore-demo-endpoint.execute-api.com/{proxy}.

8. Escolha Save (Salvar).

Testar uma API com a integração de proxy HTTP

O êxito de determinada solicitação do cliente depende do seguinte:

• Se o backend disponibilizou o endpoint de backend correspondente e, se esse for o caso, se as permissões de acesso necessárias foram concedidas.

• Se o cliente forneceu a entrada correta.

Por exemplo, a API da PetStore usada aqui não expõe o recurso /petstore. Dessa forma, você obtém uma resposta 404 Resource Not Found contendo a mensagem de erro Cannot GET /petstore.

Além disso, o cliente deve ser capaz de lidar com o formato de saída do backend para analisar o resultado corretamente. O API Gateway não se interpõe para facilitar as interações entre o cliente e o backend.

Para testar uma API integrada ao site PetStore usando a integração de proxy HTTP por meio do recurso de proxy

1. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

2. Em Tipo de método, selecione GET.

3. Em Caminho, em proxy, insira petstore/pets.

4. Em Strings de consulta, digite type=fish.

5. Escolha Test (Testar).

   

   Como o site de backend oferece suporte para a solicitação GET /petstore/pets?type=fish, ele retorna uma resposta bem-sucedida semelhante à seguinte:

   [
     {
       "id": 1,
       "type": "fish",
       "price": 249.99
     },
     {
       "id": 2,
       "type": "fish",
       "price": 124.99
     },
     {
       "id": 3,
       "type": "fish",
       "price": 0.99
     }
   ]

   Se você tentar chamar GET /petstore, receberá uma resposta 404 com uma mensagem de erro Cannot GET /petstore. Isso acontece porque o backend não oferece suporte à operação especificada. Se você chamar GET /petstore/pets/1, receberá uma resposta 200 OK com a carga a seguir, pois a solicitação recebe suporte do site PetStore.

   {
     "id": 1,
     "type": "dog",
     "price": 249.99
   }

Também é possível usar um navegador para testar a API. Implante a API e associe-a a um estágio para criar o URL de invocação da API.

Para implantar sua API

1. Escolha Deploy API (Implantar API).

2. Em Estágio, selecione Novo estágio.

3. Em Stage name (Nome do estágio), insira test.

4. (Opcional) Em Description (Descrição), insira uma descrição.

5. Escolha Implantar.

Agora, os clientes podem chamar sua API.

Como invocar a API

1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

2. Selecione a API.

3. No painel de navegação principal, selecione Estágio.

4. Em Detalhes do estágio, escolha o ícone de cópia para copiar o URL de invocação da API.

   Copie o URL de invocação da API em um navegador web.

   O URL deve ser semelhante a https://abcdef123.execute-api.us-east-2.amazonaws.com/test/petstore/pets?type=fish.

   Seu navegador envia uma solicitação GET à API.

5. O resultado deve ser o mesmo que o gerado ao usar Testar no console do API Gateway.