Tutorial: Criar uma API REST importando um exemplo

Você pode usar o console do Amazon API Gateway para criar e testar uma API REST simples com a integração HTTP de um site PetStore. A definição de API é pré-configurada como um arquivo OpenAPI 2.0. Depois de carregar a definição da API no API Gateway, é possível usar o console do API Gateway para examinar a estrutura básica da API ou simplesmente implantar e testar a API.

A API PetStore de exemplo oferece suporte aos métodos a seguir para que um cliente acesse o site de backend HTTP de http://petstore-demo-endpoint.execute-api.com/petstore/pets.

nota

Esse tutorial usa um endpoint HTTP como exemplo. Ao criar suas próprias APIs, recomendamos que você use endpoints HTTPS para as integrações HTTP.

• GET /: para acesso de leitura do recurso raiz da API que não está integrado a qualquer endpoint de backend. O API Gateway responde com uma visão geral do site PetStore. Este é um exemplo do tipo de integração MOCK.

• GET /pets: para acesso de leitura ao recurso /pets da API que está integrado ao recurso de backend /pets de nome idêntico. O backend retorna uma página de animais de estimação disponíveis na PetStore. Este é um exemplo do tipo de integração HTTP. O URL do endpoint de integração é http://petstore-demo-endpoint.execute-api.com/petstore/pets.

• POST /pets: para acesso de gravação ao recurso /pets da API que está integrado ao recurso de backend /petstore/pets. Depois de receber uma solicitação correta, o backend adiciona o animal de estimação especificado à PetStore e retorna o resultado para o autor da chamada. A integração também é HTTP.

• GET /pets/{petId}: para acesso de leitura a um animal de estimação conforme identificado por um valor petId especificado como uma variável de caminho do URL da solicitação recebida. Este método também tem o tipo de integração HTTP. O backend retorna o animal de estimação especificado encontrado na PetStore. O URL do endpoint HTTP de backend é http://petstore-demo-endpoint.execute-api.com/petstore/pets/n, onde n é um número inteiro como o identificador do animal de estimação consultado.

A API oferece suporte ao acesso de CORS através dos métodos OPTIONS do tipo de integração MOCK. O API Gateway retorna os cabeçalhos necessários para suporte ao acesso de CORS.

O procedimento a seguir descreve as etapas para criar e testar uma API a partir de um exemplo usando o console do API Gateway.

Para importar, criar e testar a API de exemplo

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

2. Faça um dos procedimentos a seguir:

   • Para criar sua primeira API, em API REST, escolha Criar.

   • Se você criou uma API antes, escolha Criar API e, depois, escolha Criar para API REST.

3. Em Criar API REST, selecione API de exemplo e escolha Importar para criar a API de exemplo.

   

   É possível percorrer a definição do OpenAPI para conhecer os detalhes dessa API de exemplo antes de selecionar Importar.

4. No painel de navegação principal, selecione Recursos. A API recém-criada é mostrada da seguinte forma:

   

   O painel Resources (Recursos) mostra a estrutura da API criada como uma árvore de nós. Os métodos de API definidos em cada recurso são as extremidades da árvore. Quando um recurso é selecionado, todos os respectivos métodos são listados na tabela Métodos à direita. Com cada método, são exibidos o tipo de método, o tipo de integração, o tipo de autorização e o requisito da chave de API.

5. Para visualizar os detalhes de um método, modificar sua configuração ou testar a invocação do método, escolha o nome do método na lista de métodos ou na árvore de recursos. Aqui, escolhemos o método POST /pets como uma ilustração:

   

   O painel Execução de método resultante apresenta uma visão lógica da estrutura e dos comportamentos do método escolhido (POST /pets).

   A Solicitação de método e a Resposta de método representam a interface da API com o front-end, ao passo que a Solicitação de integração e a Resposta de integração representam a interface da API com o back-end.

   Um cliente usa a API para acessar um recurso de back-end por meio da Solicitação de método. Se necessário, o API Gateway converte a solicitação do cliente no formato aceitável para o back-end em Solicitação de integração antes de encaminhá-la ao back-end. A solicitação transformada é conhecida como a solicitação de integração. De maneira semelhante, o back-end retorna a resposta ao API Gateway em Resposta de integração. Depois, o API Gateway a roteia para Method Response (Resposta de método) antes de enviá-la ao cliente. Novamente, se necessário, o API Gateway poderá mapear os dados da resposta de backend para um formulário esperado pelo cliente.

   Para o método POST em um recurso da API, a carga de solicitação de método poderá ser passada para a solicitação de integração sem modificação, se a carga de solicitação de método estiver no mesmo formato que a carga de solicitação de integração.

   A solicitação do método GET / usa o tipo de integração MOCK e não está vinculada a nenhum endpoint de backend real. A Resposta de integração correspondente é configurada para gerar uma página HTML estática. Quando o método é chamado, o API Gateway simplesmente aceita a solicitação e retorna imediatamente a resposta de integração configurada para o cliente como Resposta de método. Você pode usar a integração fictícia para testar uma API sem exigir um endpoint de backend. Você também pode usá-la para atender a uma resposta local, gerada a partir de um modelo de mapeamento de corpo de resposta.

   Como desenvolvedor de APIs, você pode controlar os comportamentos das interações de front-end da sua API, configurando a solicitação do método e uma resposta do método. Você controla os comportamentos das interações de backend da sua API configurando a solicitação de integração e a resposta da integração. Isso envolve mapeamentos de dados entre um método e sua integração correspondente. Por enquanto, nos concentraremos em testar a API para fornecer uma experiência de usuário de ponta a ponta.

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

7. Por exemplo, para testar o método POST /pets, digite a carga útil {"type": "dog","price": 249.99} a seguir no Corpo da solicitação e escolha Testar.

   

   A entrada especifica os atributos do animal de estimação que queremos adicionar à lista de animais de estimação no site PetStore.

8. Os resultados são exibidos da seguinte forma:

   

   A entrada Log da saída mostra as alterações de estado da solicitação de método para a solicitação de integração e da resposta de integração para a resposta de método. Isso pode ser útil para solucionar problemas com erros de mapeamento que causam a falha da solicitação. Neste exemplo, nenhum mapeamento é aplicado: a carga da solicitação do método é passada por meio de uma solicitação de integração para o backend e, de maneira semelhante, a resposta do backend é passada por meio da resposta da integração para a resposta do método.

   Para testar a API usando um cliente diferente do recurso test-invoke-request do API Gateway, é necessário primeiro implantar a API em um estágio.

9. Para implantar o exemplo de API, selecione Implantar API.

   

10. Em Estágio, selecione Novo estágio e insira test.

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

12. Escolha Implantar.

13. No painel Estágios resultante, em Detalhes do estágio, Invocar URL exibe o URL para invocar a solicitação de método GET / da API.

    

14. Escolha o ícone de cópia para copiar o URL de invocação da API e insira o URL de invocação da sua API em um navegador da web. Uma resposta bem-sucedida retornará o resultado, gerada a partir do modelo de mapeamento na resposta de integração.

15. No painel de navegação Stages (Estágios), expanda o estágio test (teste), selecione GET em /pets/{petId} e, em seguida, copie o valor de Invoke URL (Invocar URL) de https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}. {petId} representa uma variável de caminho.

    Cole o valor de Invoke URL (Invocar URL) (obtido na etapa anterior) na barra de endereços de um navegador, substituindo {petId} por, por exemplo, 1 e pressione Enter para enviar a solicitação. Uma resposta 200 OK será retornada com a seguinte carga JSON:

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

    É possível invocar o método de API conforme mostrado porque seu tipo Authorization (Autorização) está definido como NONE. Se a autorização AWS_IAM fosse usada, você assinaria a solicitação usando os protocolos Signature Version 4 (SigV4). Para obter um exemplo dessa solicitação, consulte Tutorial: Criar uma API REST com integração não proxy HTTP.