Bem-vindo à parte 2 do nosso artigo sobre APIs Serveless. Lembra como o último artigo foi simples e trivial? Pois bem, hoje falaremos de API Gateway. Relembrando o artigo anterior, o API Gateway é uma forma de transformar seus pedidos HTTP em eventos que disparem uma determinada função Lambda.

O funcionamento do API Gateway é simples. Ele agrupa diversos recursos (caminhos URLs), cada um com seus métodos HTTP específicos (GET, POST, PUT, etc). Cada método de um recurso precisa ser configurado individualmente, por isso configurar o API Gateway pode ser uma tarefa trabalhosa e cheia de detalhes sem uma ferramenta automatizada. Vamos à ação…

Criando uma API

Antes de mais nada, precisamos criar um endpoint que vai agrupar nossos recursos. Vá no Console do API Gateway, clique em Create new API e crie uma nova API. Para isso, só é necessário o nome da sua API:

Pronto, o endpoint final é uma URL composta da região onde API foi criada, sua ID interna e o stage (dev, qa, prod) desejado, veremos isso em detalhes depois. Algo importante de frisar é que qualquer modificação feita no console só será válida após o deploy para algum stage.

Criando um recurso

Agora vamos criar um path nessa URL (ou recurso) e associar um dos verbos HTTP para esse caminho. Vá em Action > Create resource e crie um novo recurso chamado “mycalc”.

Depois, escolha o recurso “mycalc” na barra lateral e selecione Actions > Create Method e adicione o methodo POST.

Depois de selecionar o método, você precisará configurar uma integração, que é o elemento responsável por processar o pedido de fato, e no nosso caso será uma função lambda. Para configurá-lo, primeiro selecione lambda function, depois a região onde a função lambda desejada se encontra e por final o nome da função. Clique em Save.

Pronto, agora temos um método POST no recurso /mycalc. É possível associar a cada recurso apenas um verbo HTTP de cada tipo (GET, POST, PUT…).

Fluxo de execução de um método

Agora vamos para a parte trabalhosa, configurar o método POST do recurso /mycalc.

Antes de por mão a massa, vamos observar o que o console nos mostra quando selecionamos um método de um recurso:

Observe que existe um fluxo que passa por cinco estágios desde o pedido HTTP feito ao endpoint do API Gateway até o retorno para o cliente que fez o pedido. Antes de entrarmos em detalhes, vale explicar o que cada passo representa e faz com o pedido HTTP.

Method Request: Configura o método de autenticação do método e os possíveis parâmetros que ele pode receber. Nesse artigo não vamos explorar a parte de autenticação, apenas o processamento do pedido com seus parâmetros.

Integration: Nesse bloco configuramos quem vai fazer o processamento de fato do pedido (um outro endpoint, uma função lambda etc). Nesse bloco também montamos o objeto que será passado para a próxima etapa. Esse objeto é o events, que vimos no artigo anterior. Nele, colocaremos os parâmetros que configuramos no bloco anterior (Method Request), além de outros meta dados se necessário.

Integration Response: Para o API Gateway, a resposta da integração não passa de um texto. Ele não consegue discernir os status do processo desse pedido. Portanto, nesse bloco fazemos o mapeamento das respostas com os status (200, 400, 500, etc) por meio de Expressões Regulares. Parece esquisito (e é).

Response Parameters: Esse é o último passo da respostas. Aqui nós configuramos as possíveis respostas que nosso método pode resultar e seus headers.

Esse fluxo é executado sempre que um pedido é feito a um recurso de uma API do API Gateway.

Configurando um método de um recurso

Agora que temos um bom entendimento do que estamos fazendo, vamos, finalmente, configurar o método POST do recurso /mycalc:.

Seguindo o fluxo que o console do API Gateway nos mostra, vamos primeiro configurar o Method Request do método POST.

Selecione Method Request, expanda URL Query String Parameters e adicione os valores “operation” e “limit”. Com isso, configuramos o endpoint a esperar esses dois valores no formato de querystrings, por exemplo: /mycalc?operation=fibonacci?limit=10. Esses dados serão repassados para o próximo passo do fluxo do API Gateway.

Agora precisamos configurar o objeto event que será passado para o lambda a partir do API Gateway. Para isso, volte para o menu do método POST e clique em Integration Request. Nessa tela, que já vimos quando criamos o método, expanda Body Mapping Templates, e em seguida crie um content-type do tipo application/json. Ao lado, escreva o JSON da imagem abaixo.

As duas primeiras linhas são autoexplicativas, estamos apenas pegando os valores passados inline na URL e associando a uma key do objeto JSON que será passado ao lambda. A última linha simplesmente diz para associar todos os dados de uma requisição POST para a chave data.

Agora vamos mudar um pouco o fluxo. Antes de configurarmos o Integration Response, primeiro precisamos definir quais as possíveis respostas do método POST. Então, primeiro vamos configurar Method Response. Nessa listagem, temos todos os tipos possíveis que esse endpoint irá configurar. O Status 200 já existe como default. Nesse exemplo adicionei mais um status 400 e apertei no check lateral.

Depois, volte para o menu e escolha Integration Response. Lembre-se que o lambda apenas recebe JSON e devolve texto. Portanto, temos que mapear as respostas de texto em HTTP Status. Para isso, utilizaremos um regex. Nesse menu, crie mais uma resposta, coloque ERROR* nela e escolha o status 400. Com isso, estamos efetivamente dizendo que qualquer resposta vindo do lambda que comece com ERROR irá gerar um HTTP Status 400 no API Gateway.

O Status 200 já é predefinido, e caso nenhum outro mapeamento seja válido, o método responderá 200 como default.

Pronto! Acabamos de configurar nosso primeiro método de nosso primeiro recurso de nossa primeira API! (quantas vitórias rs)

Deployando nossa aplicação

Como citei no início do artigo, todas essas configurações foram salvas, porém não estão em vigor. Para torná-las públicas, clique em Actions > Deploy API.

Agora informe qual o nome do stage dessa API. Caso já exista um anterior, ele será sobrescrito.

No final, você receberá sua URL pública.

Pronto, sua API esta pública e pronta para usar. Você pode testá-la utilizando alguma aplicação para mockar pedidos, como o POSTMAN.

Como pode ver, nossa API está funcionando perfeitamente de forma integrada com o Lambda.

Agora vamos testar o envio dos dados via POST, e não por query parameters. Para isso, precisamos modificar nosso código para extrair os dados do objeto data.

Com essa modificação na linha 9, nós passamos a usar os valores enviados por POST (como configuramos o request template anteriormente.) Vamos testá-lo para ver se é funcional.

Pronto! Funciona!

Neste artigo vimos como criar um método de um recurso de uma API usando o Lambda para processar o pedido. Mas você já deve ter observado o quão trabalhoso isso pode se tornar para configurar uma API inteira com centenas de pedidos.

No terceiro artigo da série você verá algumas dicas e melhores práticas que aprendemos na nossa jornada utilizando API Gateway e Lambda. Fique atento!

Tem alguma dúvida ou algo a acrescentar? Aproveite os campos abaixo.