Tutorial: Criar uma API REST com integração não proxy 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.

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.

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

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

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

6. 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 PetStore site (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) Para fins de ilustração, criaremos um /pets recurso como filho da raiz e exporemos um método GET nesse recurso para que um cliente recupere uma lista de itens de animais de estimação disponíveis no PetStore site.

Como criar um recurso /pets

1. Selecione o recurso / e, depois, escolha Criar recurso.

2. Mantenha Recurso proxy desativado.

3. Mantenha Caminho do recurso como /.

4. Em Resource Name (Nome do recurso), insira pets.

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

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

2. Escolha Criar método.

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

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

5. Mantenha a opção Integração do proxy HTTP desativada.

6. Em Método HTTP, selecione GET.

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

8. Em Manuseio de conteúdo, selecione Passagem.

9. Mantenha o Tempo limite padrão ativado.

10. Escolha Criar método.

O PetStore site permite que você recupere uma lista de Pet itens por tipo de animal de estimação (como “Cachorro” ou “Gato”) em uma determinada página. Ele usa os parâmetros de string de consulta type e page para aceitar essa entrada. Sendo assim, precisamos adicionar os parâmetros de string de consulta à solicitação de método e mapeá-los para as strings de consulta correspondentes da solicitação de integração.

Como adicionar parâmetros de string de consulta ao método GET

1. Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.

2. Selecione Parâmetros de string de consulta de URL e faça o seguinte:

   1. Escolha Add query string (Adicionar string de consulta).

   2. Em Nome, insira type.

   3. Mantenha Obrigatório e Armazenamento em cache desativados.

   Repita as etapas anteriores para criar uma string de consulta adicional com o nome page.

3. Escolha Salvar.

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 nos parâmetros da string de consulta da integração para encaminhar os valores de entrada para nosso PetStore site no back-end.

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.

2. Selecione Parâmetros de string de consulta de URL e faça o seguinte:

   1. Selecione Adicionar parâmetro de string de consulta.

   2. Em Nome, digite type.

   3. Em Mapeado de, insira method.request.querystring.type.

   4. Mantenha Armazenamento em cache desativado.

   5. Selecione Adicionar parâmetro de string de consulta.

   6. Em Nome, digite page.

   7. Em Mapeado de, insira method.request.querystring.page.

   8. Mantenha Armazenamento em cache desativado.

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

2. Em Strings de consulta, digite type=Dog&page=2.

3. Escolha Testar.

   O resultado é semelhante ao seguinte:

   

   Agora que o teste foi bem-sucedido, podemos implantar a API para torná-la disponível publicamente.

4. Escolha Deploy API (Implantar API).

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

6. Em Stage name (Nome do estágio), insira Prod.

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

8. Escolha Implantar.

9. (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 e cURL 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 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} no URL da 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 {petId}.

Como criar o recurso {petId}

1. Selecione o recurso /pets e, depois, escolha Criar recurso.

2. Mantenha Recurso proxy desativado.

3. Em Caminho do recurso, selecione/pets.

4. Em Resource Name (Nome do recurso), insira {petId}.

   Use as chaves ({ }) ao redor de petId para que /pets/{petId} seja exibido.

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

6. 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 /{petId} e, depois, Criar método.

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

3. Em Tipo de integração, selecione Integração HTTP.

4. Mantenha a opção Integração do proxy HTTP desativada.

5. Em Método HTTP, selecione GET.

6. Em URL do endpoint, insira http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}.

7. Em Manuseio de conteúdo, selecione Passagem.

8. Mantenha o Tempo limite padrão ativado.

9. Escolha Criar método.

Agora você vai associar o parâmetro de caminho {petId} ao parâmetro de caminho {id} no endpoint HTTP.

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.

2. Selecione Parâmetros de caminho de URL.

3. O API Gateway cria um parâmetro de caminho para a solicitação de integração chamado petId. Isso não funcionará para o back-end. O endpoint HTTP usa {id} como o parâmetro de caminho. Renomeie petId para 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.

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

2. Em Caminho para petId, insira 4.

3. 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 Deploy API (Implantar API).

2. Em Estágio, selecione Prod.

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

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

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

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

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

• Para obter informações sobre como transformar cargas úteis de solicitação e resposta, consulte Configurar transformações de dados no API Gateway.

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