Tutorial: Criar uma API REST importando um exemplo - Amazon API Gateway

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.

  • 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. Se você ainda não tiver feito isso, conclua as etapas em Pré-requisitos para começar a usar o API Gateway.

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

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

  4. Em Create new API (Criar nova API), escolha Example API (API de exemplo) e escolha Import (Importar) para criar a API de exemplo. Para a sua primeira API, o console do API Gateway começa com esta opção como padrão.

    Você pode percorrer a definição do OpenAPI para conhecer os detalhes dessa API de exemplo antes de escolher Import (Importar).

  5. 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 seus métodos são listados no painel Methods (Métodos) à direita. Cada método exibe um breve resumo abaixo dele, incluindo sua URL de endpoint, o tipo de autorização e o requisito de Chave de API.

  6. 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 Method Execution (Execução de método) apresenta uma exibição lógica da estrutura e dos comportamentos do método escolhido (POST /pets): Method Request (Solicitação de método) e Method Response (Resposta de método) são a interface da API com o front-end da API (um cliente), enquanto Integration Request (Solicitação de integração) e Integration Response (Resposta de integração) são interface da API com o backend (http://petstore-demo-endpoint.execute-api.com/petstore/pets). Um cliente usa a API para acessar um recurso de backend por meio da Method Request (Solicitação de método). O API Gateway converte a solicitação do cliente, se necessário, no formato aceitável para o backend em Integration Request (Solicitação de integração) antes de encaminhá-la para o backend. A solicitação transformada é conhecida como a solicitação de integração. De maneira semelhante, o backend retorna a resposta para o API Gateway em Integration Response (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 Integration Response (Resposta de integração) correspondente é configurada para retornar 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 Method Response (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. Abordamos a configuração do método em Tutorial: Criar uma API REST com integração não proxy HTTP. Por enquanto, nos concentraremos em testar a API para fornecer uma experiência de usuário de ponta a ponta.

  7. Escolha Test (Testar) mostrado em Client (Cliente) (como mostra a imagem anterior) para iniciar o teste. Por exemplo, para testar o método POST /pets, digite a seguinte carga útil {"type": "dog","price": 249.99} no Request Body (Corpo da solicitação) antes de escolher o botão Test (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 Logs 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 uma API de exemplo, selecione a API PetStore e depois escolha Deploy API (Implantar API) no menu Actions (Ações).

    Em Deploy API (Implantar API), para Deployment stage (Estágio de implantação), escolha [New Stage] ([Novo estágio]), pois essa é a primeira implantação da API. Digite um nome (por exemplo, test) em Stage name (Nome do estágio) e, opcionalmente, digite as descrições em Stage description (Descrição do estágio) e Deployment description (Descrição da implantação). Escolha Deploy (Implantar).

    No painel Stage Editor (Editor de estágio) resultante, Invoke URL (Invocar URL) exibe a URL para invocar a solicitação de método GET / da API.

  10. Em Stage Editor (Editor de estágio), siga o link Invoke URL (Invocar URL) para enviar a solicitação do método GET / em um navegador. Uma resposta bem-sucedida retornará o resultado, gerada a partir do modelo de mapeamento na resposta de integração.

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