# Escolher um tutorial de integração HTTP
Para criar uma API com integração HTTP, você pode usar uma integração de proxy HTTP ou uma integração HTTP personalizada.
Em uma integração de proxy HTTP, só é necessário definir o método HTTP e o URI de endpoint HTTP de acordo com os requisitos de back-end. Recomendamos o uso da integração de proxy HTTP sempre que possível para aproveitar a configuração simplificada da API.
Talvez você queira usar uma integração HTTP personalizada se precisar transformar os dados de solicitação do cliente para o back-end ou transformar os dados de resposta do back-end para o cliente.
**Topics**
+ [Tutorial: Crie uma API REST com uma integração de proxy de HTTP](api-gateway-create-api-as-simple-proxy-for-http.md)
+ [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md)
# Tutorial: Crie uma API REST com uma integração de proxy de 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](api-gateway-known-issues.md).
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`.
**Topics**
+ [Criar uma API com integração de proxy HTTP usando o console do API Gateway](#api-gateway-create-api-as-simple-proxy-for-http-build)
+ [Testar uma API com a integração de proxy HTTP](#api-gateway-create-api-as-simple-proxy-for-http-test)
## 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: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md), 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](https://console.aws.amazon.com/apigateway).
1. 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).
1. Em **API name (Nome da API)**, insira **HTTPProxyAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. 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 **/\$1proxy\$1\$1****
1. Selecione a API.
1. No painel de navegação principal, selecione **Recursos**.
1. Selecione **Criar recurso**.
1. Ative **Recurso proxy**.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1proxy\$1\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
![\[Crie um recurso filho.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-simple-proxy-create-proxy-resource-new-console.png)
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**/\$1proxy\$1\$1**.
1. Selecione o método **ANY**.
1. 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.
1. Em **Tipo de integração**, selecione **HTTP**.
1. Ative **Integração de proxy HTTP**.
1. Em **Método HTTP**, selecione **ANY**.
1. Em **URL do endpoint**, insira **http://petstore-demo-endpoint.execute-api.com/\$1proxy\$1**.
1. Escolha **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.
1. Em **Tipo de método**, selecione `GET`.
1. Em **Caminho**, em **proxy**, insira **petstore/pets**.
1. Em **Strings de consulta**, digite **type=fish**.
1. Escolha **Testar**.
![\[Use o recurso de teste para testar um método.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-simple-proxy-petstore-call-proxy-resource-new-console.png)
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 **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **test**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. 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](https://console.aws.amazon.com/apigateway).
1. Selecione a API.
1. No painel de navegação principal, selecione **Estágio**.
1. 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.
1. O resultado deve ser o mesmo que o gerado ao usar **Testar** no console do API Gateway.
# Tutorial: Crie uma API REST com uma integração de não proxy de HTTP
Neste tutorial, você criará uma API do zero usando o console do Amazon API Gateway. Você pode pensar no console como um estúdio de design de API e usá-lo para definir o escopo dos recursos da API, testar seus comportamentos, criar a API e implantá-la em estágios.
**Topics**
+ [Criar uma API com integração personalizada HTTP](#api-gateway-create-resource-and-methods)
+ [(Opcional) Associar parâmetros de solicitação](#api-gateway-create-resources-and-methods-next-steps)
## Criar uma API com integração personalizada HTTP
Esta seção orienta você pelas etapas necessárias para criar recursos, expor métodos em um recurso, configurar um método para alcançar os comportamentos de API desejados e testar e implantar a API.
Nesta etapa, você cria uma API vazia. Nas etapas a seguir, você vai criar recursos e métodos para conectar a API ao endpoint `http://petstore-demo-endpoint.execute-api.com/petstore/pets` usando uma integração HTTP sem proxy.
**Como criar uma API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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).
1. Em **API name (Nome da API)**, insira **HTTPNonProxyAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
A árvore **Resources (Recursos)** mostra o recurso raiz (`/`) sem métodos. Neste exercício, criaremos a API com a integração HTTP personalizada do site da PetStore (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) Para fins de ilustração, vamos criar um recurso `/pets` como um filho da raiz e expor um método GET nesse recurso para um cliente recuperar uma lista de itens de animais de estimação disponíveis no site PetStore.
**Como criar um recurso /pets**
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **pets**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Nesta etapa, você vai criar um método `GET` para o recurso **/pets**. O método `GET` é integrado ao site `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. São outras opções para um método de API:
+ **POST**, usado principalmente para criar recursos filho.
+ **PUT**, usado principalmente para atualizar recursos existentes (e, embora não seja recomendado, pode ser usado para criar recursos filho).
+ **DELETE**, usado para excluir recursos.
+ **PATCH**, usado para atualizar recursos.
+ **HEAD**, usado, principalmente em cenários de teste. É o mesmo que GET, mas não retorna a representação do recurso.
+ **OPTIONS**, que pode ser usado por autores de chamadas para obter informações sobre opções de comunicação disponíveis para o serviço de destino.
Para o **HTTP method (Método HTTP)** da solicitação de integração, você deve escolher um que seja compatível com o backend. Para `HTTP` ou `Mock integration`, faz sentido que a solicitação de método e a solicitação de integração usem o mesmo verbo HTTP. Para outros tipos de integração, a solicitação de método provavelmente usará um verbo HTTP diferente da solicitação de integração. Por exemplo, para chamar uma função do Lambda, a solicitação de integração deve usar `POST` para invocar a função, enquanto a solicitação de método pode usar qualquer verbo HTTP, dependendo da lógica da função do Lambda.
**Como criar um método `GET` no recurso **/pets****
1. Selecione o recurso **/pets**.
1. Escolha **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Integração HTTP**.
1. Mantenha a opção **Integração do proxy HTTP** desativada.
1. Em **Método HTTP**, selecione **GET**.
1. Em **URL do endpoint**, insira **http://petstore-demo-endpoint.execute-api.com/petstore/pets**.
O site PetStore permite que você recupere uma lista de itens `Pet` por tipo de animal de estimação, por exemplo, “Cão” ou “Gato”, em uma página específica.
1. Em **Manuseio de conteúdo**, selecione **Passagem**.
1. Selecione **Parâmetros de string de consulta de URL**.
Ele usa os parâmetros de string de consulta `type` e `page` para aceitar uma entrada. Adicione os parâmetros de string de consulta à solicitação de método e mapeie-os para os parâmetros de string de consulta correspondentes da solicitação de integração.
1. Para adicionar parâmetros de string de consulta, faça o seguinte:
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, insira **type**.
1. Mantenha **Obrigatório** e **Armazenamento em cache** desativados.
Repita as etapas anteriores para criar uma string de consulta adicional com o nome **page**.
1. Escolha **Criar método**.
O cliente agora pode fornecer um tipo de animal de estimação e um número de página como parâmetros de string de consulta ao enviar uma solicitação. Esses parâmetros de entrada devem ser mapeados para parâmetros da sequência de consulta da integração para encaminhar os valores de entrada para nosso site PetStore no backend.
**Como associar parâmetros de entrada à solicitação de integração**
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de string de consulta de URL** e faça o seguinte:
1. Selecione **Adicionar parâmetro de string de consulta**.
1. Em **Nome**, digite **type**.
1. Em **Mapeado de**, insira **method.request.querystring.type**.
1. Mantenha **Armazenamento em cache** desativado.
1. Selecione **Adicionar parâmetro de string de consulta**.
1. Em **Nome**, digite **page**.
1. Em **Mapeado de**, insira **method.request.querystring.page**.
1. Mantenha **Armazenamento em cache** desativado.
1. Escolha **Salvar**.
**Como testar a API**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Strings de consulta**, digite **type=Dog&page=2**.
1. Escolha **Testar**.
O resultado é semelhante ao seguinte:
![\[Testar/invocar o resultado do método GET on pets\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-step-by-step-test-invoke-get-on-pets-result-new-console.png)
Agora que o teste foi bem-sucedido, podemos implantar a API para torná-la disponível publicamente.
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **Prod**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
1. (Opcional) Em **Detalhes do estágio**, para **Invocar URL**, é possível selecionar o ícone de cópia para copiar o URL de invocação da API. Você pode usá-lo com ferramentas, como [Postman](https://www.postman.com) e [cURL](https://curl.se/) para testar sua API.
Se você usar um SDK para criar um cliente, poderá chamar os métodos expostos pelo SDK para assinar a solicitação. Para obter detalhes da implementação, consulte o [SDK da AWS](https://aws.amazon.com/developer/tools/) de sua escolha.
**nota**
Quando alterações são feitas na sua API, você deve reimplantá-la para disponibilizar os recursos novos ou atualizados antes de invocar novamente a URL da solicitação.
## (Opcional) Associar parâmetros de solicitação
### Mapear parâmetros de solicitação para uma API do API Gateway
Este tutorial mostra como criar um parâmetro de caminho de `{petId}` na solicitação de método da API para especificar um ID de item, associá-lo ao parâmetro de caminho `{id}` no URL da solicitação de integração e enviar a solicitação ao endpoint HTTP.
**nota**
Se você digitar uma letra de tamanho incorreto, por exemplo, minúscula em vez de maiúscula, poderá causar erros mais adiante no processo.
#### Etapa 1: Criar recursos
Nesta etapa, você vai criar um recurso com um parâmetro de caminho \$1petId\$1.
**Como criar o recurso \$1petId\$1**
1. Selecione o recurso **/pets** e, depois, escolha **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Em **Caminho do recurso**, selecione**/pets**.
1. Em **Resource Name (Nome do recurso)**, insira **\$1petId\$1**.
Use as chaves (`{ }`) ao redor de `petId` para que **/pets/\$1petId\$1** seja exibido.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
#### Etapa 2: Criar e testar métodos
Nesta etapa, você vai criar um método `GET` com um parâmetro de caminho `{petId}`.
**Como configurar o método GET**
1. Selecione o recurso **/\$1petId\$1** e, depois, **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Integração HTTP**.
1. Mantenha a opção **Integração do proxy HTTP** desativada.
1. Em **Método HTTP**, selecione **GET**.
1. Em **URL do endpoint**, insira **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**.
1. Em **Manuseio de conteúdo**, selecione **Passagem**.
1. Mantenha o **Tempo limite padrão** ativado.
1. Escolha **Criar método**.
Agora você vai associar o parâmetro de caminho `{petId}` que você acabou de criar ao parâmetro de caminho `{id}` no URL do endpoint HTTP da solicitação de integração. O endpoint HTTP era **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**.
**Como associar o parâmetro de caminho `{petId}`**
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de caminho de URL**.
1. O API Gateway cria um parâmetro de caminho para a solicitação de integração chamado **petId**, mas ele não é válido para o URL do endpoint HTTP que você define como a integração de backend. O endpoint HTTP usa `{id}` como o parâmetro de caminho. Em **Nome**, exclua **petId** e insira **id**.
Isso mapeia o parâmetro de caminho da solicitação de método de `petId` para o parâmetro de caminho da solicitação de integração de `id`.
1. Escolha **Salvar**.
Agora teste o método.
**Como testar o método **
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Caminho** para **petId**, insira **4**.
1. Escolha **Test** (Testar).
Se bem-sucedido, o **Corpo da resposta** exibirá o seguinte:
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### Etapa 3: implantar a API
Nesta etapa, você implantará a API para poder começar a chamá-la fora do console do API Gateway.
**Para implantar a API**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Prod**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Deploy** (Implantar).
#### Etapa 4: testar a API
Nesta etapa, você sairá do console do API Gateway e usará sua API para acessar o endpoint HTTP.
1. No painel de navegação principal, selecione **Estágio**.
1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API.
A aparência será semelhante à seguinte:
```
https://my-api-id.execute-api.region-id.amazonaws.com/prod
```
1. Insira este URL na caixa de endereço da nova guia do navegador e anexe `/pets/4` ao URL antes de enviar a solicitação.
1. O navegador exibirá o seguinte:
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### Próximas etapas
É possível personalizar ainda mais a API ativando a validação de solicitações, transformando dados ou criando respostas de gateway personalizadas.
Para examinar mais formas de personalizar a API, veja os seguintes tutoriais:
+ Para obter mais informações sobre a validação de solicitação, consulte [Configurar a validação básica de solicitações no API Gateway](api-gateway-request-validation-set-up.md).
+ Para obter informações sobre como transformar cargas úteis de solicitação e resposta, consulte [Tutorial: modificar a solicitação e a resposta de integração para integrações a serviços da AWS](set-up-data-transformations-in-api-gateway.md).
+ Para obter informações sobre como criar respostas de gateway personalizadas, consulte [Configurar uma resposta de gateway para uma API REST usando o console do API Gateway](set-up-gateway-response-using-the-console.md).