AWS Builder Center
Validando Corpo de Requisições no Amazon API Gateway com JSON Schema

Validando Corpo de Requisições no Amazon API Gateway com JSON Schema

Aprenda a rejeitar payloads malformados antes que cheguem ao seu backend configurando modelos JSON Schema e validadores de requisição diretamente no API Gateway.

AWS Solutions Architect

Introdução

Ao construir APIs, uma das primeiras linhas de defesa contra dados malformados é a validação de entrada. Em vez de empurrar essa responsabilidade para o seu backend (Lambda, EC2 ou containers), você pode transferir a validação estrutural diretamente para o Amazon API Gateway. Isso garante que payloads inválidos sejam rejeitados imediatamente com um erro 400 antes de chegarem à sua camada de integração.
Neste tutorial, você criará uma REST API no API Gateway que valida o corpo da requisição de um método POST usando um  modelo JSON Schema . O modelo impõe um formato específico de timestamp via padrão regex. Para manter as coisas simples e serverless, o backend usa uma  integração mock  que retorna uma resposta fixa de sucesso. Sem funções Lambda, sem serviços externos.
O resultado: se o timestamp corresponder ao formato ISO 8601 esperado, a API retorna uma mensagem de sucesso. Se não corresponder, o API Gateway rejeita a requisição imediatamente.

O Que Você Vai Construir

  • Uma REST API com um único método POST no recurso  /events 
  • Um modelo JSON Schema que exige um campo  timestamp  correspondendo ao padrão  YYYY-MM-DDTHH:MM:SSZ 
  • Um validador de requisição que impõe o modelo antes que a requisição chegue à integração
  • Uma integração mock que retorna uma mensagem estática de sucesso

Pré-requisitos

  • Uma conta AWS com acesso ao console do API Gateway
  • Nenhum serviço ou permissão adicional necessário (integração mock não precisa de backend)

Arquitetura da Solução

A arquitetura é mínima. O cliente envia uma requisição POST com um corpo JSON. O API Gateway valida o corpo contra um modelo JSON Schema. Se a validação passar, a integração mock retorna uma resposta fixa. Se a validação falhar, o API Gateway retorna um erro 400 imediatamente.
Diagrama mostrando o fluxo de uma requisição POST do cliente até o Amazon API Gateway, onde o corpo é validado contra um modelo JSON Schema, retornando sucesso via integração mock ou erro 400 em caso de falha na validação


Step 1: Criar a REST API

1.1 Criar uma Nova API

1.1.2. Escolha Create API.
1.1.3. Em REST API, escolha Build.
1.1.4. Para API name, insira  EventValidationAPI .
1.1.5. Para Description, insira  API with request body validation using JSON Schema .
1.1.6. Para API endpoint type, selecione Regional.
1.1.7. Escolha Create API.

Step 2: Criar o Modelo

Antes de configurar o método, você precisa definir o modelo JSON Schema que descreve a estrutura esperada do corpo da requisição. O API Gateway usa  JSON Schema draft 4  para definições de modelos.

2.1 Definir o EventModel

2.1.1. No painel de navegação à esquerda, escolha Models.
2.1.2. Escolha Create model.
Tela do console do Amazon API Gateway mostrando o painel de navegação lateral com a opção Models destacada e o botão Create model disponível para criação de um novo modelo

2.1.3. Para Name, insira  EventModel .
2.1.4. Para Content type, insira  application/json .
2.1.5. Para Description, insira  Model for event submission with timestamp validation .
2.1.6. Para Model schema, cole o seguinte JSON Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "EventModel",
"type": "object",
"required": ["eventType", "timestamp"],
"properties": {
"eventType": {
"type": "string",
"enum": ["LOGIN", "LOGOUT", "PURCHASE"]
},
"timestamp": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
},
"userId": {
"type": "string"
}
}
}

2.1.7. Escolha Create model.
Tela do console do API Gateway exibindo o formulário de criação de modelo preenchido com o nome EventModel, content type application/json e o schema JSON com validação de eventType, timestamp e userId


2.2 Entendendo o Modelo

O modelo impõe as seguintes regras:
  • eventType (obrigatório): deve ser um dos valores  LOGIN ,  LOGOUT  ou  PURCHASE 
  • timestamp (obrigatório): deve ser uma string correspondendo ao padrão ISO 8601  YYYY-MM-DDTHH:MM:SSZ  (ex.:  2025-06-15T14:30:00Z )
  • userId (opcional): um identificador em formato string para o usuário
A propriedade  pattern  usa uma expressão regular para validar o formato do timestamp. Este é um recurso poderoso do JSON Schema draft 4 suportado pelo API Gateway. Se o timestamp usar um formato diferente (ex.:  15/06/2025 14:30  ou  1718456400 ), a validação falhará.

Step 3: Criar o Recurso e o Método

3.1 Criar o Recurso /events

3.1.1. No painel de navegação à esquerda, escolha Resources.
3.1.2. Selecione o recurso raiz  / .
3.1.3. Escolha Create resource.
3.1.4. Para Resource name, insira  events .
3.1.5. O Resource path será preenchido automaticamente como  /events .
3.1.6. Escolha Create resource.

3.2 Criar o Método POST com Integração Mock

3.2.1. Com o recurso  /events  selecionado, escolha Create method.
3.2.2. Para Method type, selecione POST.
3.2.3. Para Integration type, selecione Mock.
3.2.4. Escolha Create method.

Step 4: Configurar a Validação de Requisição

4.1 Atribuir o Modelo e o Validador

4.1.1. Com o método POST selecionado, vá até a aba Method request.
4.1.2. Em Method request settings, escolha Edit.
Tela do console do API Gateway mostrando a aba Method request do método POST no recurso /events com o botão Edit disponível para configuração do validador de requisição

4.1.3. Para Request validator, selecione Validate body.
4.1.4. Em Request body, escolha Add model.
4.1.5. Para Content type, insira  application/json .
4.1.6. Para Model, selecione EventModel.
4.1.7. Escolha Save.
Neste ponto, o API Gateway validará o corpo de cada requisição POST recebida contra o schema EventModel. Se o corpo não estiver em conformidade, a requisição é rejeitada com um  400 Bad Request  antes de chegar à integração mock.
Tela do console do API Gateway mostrando as configurações de Method request com o Request validator definido como Validate body e o modelo EventModel associado ao content type application/json


Step 5: Configurar a Resposta da Integração Mock

A integração mock precisa de um template de mapeamento para retornar um corpo de resposta fixo.

5.1 Configurar a Integration Request

5.1.1. Na aba Integration request, em Integration request settings, escolha Edit.
Tela do console do API Gateway mostrando a aba Integration request do método POST com o botão Edit disponível para configuração dos mapping templates da integração mock

5.1.2. Escolha Mapping templates.
5.1.3. Escolha Add mapping template.
5.1.4. Para Content type, insira  application/json .
5.1.5. Você verá um dropdown Generate template entre o campo de content type e o campo do corpo do template. Este é um recurso de conveniência que preenche o editor com templates de exemplo em VTL (Velocity Template Language) baseados nos seus modelos ou um template passthrough. Para este tutorial, ignore-o e digite o template manualmente.
5.1.6. Para Template body, insira:
{"statusCode": 200}

5.1.7. Escolha Save.
Este template informa à integração mock para retornar um código de status 200. É o mecanismo que seleciona qual resposta de integração será usada.
Tela do console do API Gateway exibindo o mapping template configurado para a Integration request com content type application/json e corpo do template contendo statusCode 200


5.2 Configurar a Integration Response

5.2.1. Na aba Integration response, para a Default - Response, escolha Edit.
Tela do console do API Gateway mostrando a aba Integration response com a Default Response listada e o botão Edit disponível para configuração do template de resposta

5.2.2. Escolha Mapping templates.
5.2.3. Para Content type, insira  application/json . Se um mapping template já existir para este content type, selecione-o para editar.
5.2.4. Para Template body, insira:
{"message": "Event registered successfully"}

5.2.5. Escolha Save.
Esta é a resposta que o cliente recebe quando o corpo da requisição passa na validação.
Tela do console do API Gateway exibindo o mapping template da Integration response configurado com content type application/json e corpo contendo a mensagem Event registered successfully


Step 6: Testar a API

Você pode usar o recurso de teste integrado no console do API Gateway para validar o comportamento sem fazer deploy da API.

6.1 Testar com um Corpo Válido

6.1.1. Com o método POST selecionado, escolha a aba Test. Pode ser necessário clicar na seta à direita para exibir a aba.
6.1.2. Para Request body, cole:
{
"eventType": "LOGIN",
"timestamp": "2025-06-15T14:30:00Z",
"userId": "user-abc-123"
}

6.1.3. Escolha Test.
6.1.4. Resultado esperado:
  • Status: 200
  • Response body:  {"message": "Event registered successfully"} 
Tela do console do API Gateway mostrando o resultado do teste do método POST com um corpo JSON válido contendo eventType LOGIN, timestamp no formato correto e userId, retornando status 200 e a mensagem Event registered successfully


6.2 Testar com um Formato de Timestamp Inválido

6.2.1. Para Request body, cole:
{
"eventType": "LOGIN",
"timestamp": "15/06/2025 14:30",
"userId": "user-abc-123"
}

6.2.2. Escolha Test.
6.2.3. Resultado esperado:
  • Status: 400
  • Response body:  {"message": "Invalid request body"} 
Na seção Logs na parte inferior da saída de teste, você verá o erro de validação específico indicando que a string do timestamp não corresponde ao padrão esperado.
Tela do console do API Gateway mostrando o resultado do teste do método POST com timestamp no formato 15/06/2025 14:30 que não corresponde ao padrão regex, retornando status 400 e mensagem Invalid request body


6.3 Testar com um Campo Obrigatório Ausente

6.3.1. Para Request body, cole:
{
"eventType": "PURCHASE"
}

6.3.2. Escolha Test.
6.3.3. Resultado esperado:
  • Status: 400
  • Response body:  {"message": "Invalid request body"} 
Os logs indicarão que a propriedade obrigatória  timestamp  está ausente no objeto.
Tela do console do API Gateway mostrando o resultado do teste do método POST com corpo JSON contendo apenas eventType PURCHASE sem o campo obrigatório timestamp, retornando status 400 e mensagem Invalid request body


6.4 Testar com um Valor de Enum Inválido

6.4.1. Para Request body, cole:
{
"eventType": "DELETE",
"timestamp": "2025-06-15T14:30:00Z"
}

6.4.2. Escolha Test.
6.4.3. Resultado esperado:
  • Status: 400
  • Response body:  {"message": "Invalid request body"} 
A validação rejeita a requisição porque  DELETE  não está entre os valores enum permitidos.
Tela do console do API Gateway mostrando o resultado do teste do método POST com eventType definido como DELETE que não está na lista de valores permitidos, retornando status 400 e mensagem Invalid request body


Step 7: Fazer Deploy da API (Opcional)

Se você quiser testar a API externamente usando curl ou Postman, é necessário fazer o deploy.

7.1 Fazer Deploy em um Stage

7.1.1. Escolha Deploy API.
7.1.2. Para Stage, selecione New stage.
7.1.3. Para Stage name, insira  dev .
7.1.4. Escolha Deploy.
7.1.5. Anote a Invoke URL exibida no topo. Ela terá o formato:
https://<api-id>.execute-api.<region>.amazonaws.com/dev


7.2 Testar com curl

Com um corpo válido:
curl -X POST https://<api-id>.execute-api.<region>.amazonaws.com/dev/events \
-H "Content-Type: application/json" \
-d '{"eventType": "LOGIN", "timestamp": "2025-06-15T14:30:00Z", "userId": "user-123"}'

Resposta esperada:
{"message": "Event registered successfully"}

Terminal mostrando o comando curl enviando uma requisição POST para o endpoint deployado do API Gateway com corpo JSON válido e recebendo a resposta com mensagem Event registered successfully

Com um timestamp inválido:
curl -X POST https://<api-id>.execute-api.<region>.amazonaws.com/dev/events \
-H "Content-Type: application/json" \
-d '{"eventType": "LOGIN", "timestamp": "2025-06-15 14:30:00", "userId": "user-123"}'

Resposta esperada:
{"message": "Invalid request body"}

Terminal mostrando o comando curl enviando uma requisição POST para o endpoint deployado do API Gateway com timestamp no formato incorreto e recebendo a resposta de erro Invalid request body com status 400


Step 8: Limpeza dos Recursos

Para evitar possíveis cobranças, exclua os recursos que você criou.

8.1 Excluir a API

8.1.1. No console do API Gateway, selecione a EventValidationAPI.
8.1.2. Escolha Delete API.
8.1.3. Confirme a exclusão digitando o nome da API e escolhendo Delete.

Conclusão

Neste tutorial, você construiu uma REST API que valida corpos de requisição usando modelos JSON Schema diretamente no Amazon API Gateway. Os principais aprendizados são:
  • A validação acontece antes da integração: requisições malformadas nunca chegam ao seu backend, reduzindo invocações desnecessárias e melhorando o diagnóstico de erros.
  • Propriedade  pattern  do JSON Schema: permite validação de formato baseada em regex para strings como timestamps, UUIDs, endereços de e-mail ou identificadores personalizados.
  • Integração mock: permite prototipar e testar a lógica de validação sem fazer deploy de nenhuma infraestrutura de backend.
  • CloudWatch Logs: quando a validação falha, o API Gateway registra as violações específicas do schema, tornando a depuração simples e direta.
Esta abordagem é particularmente útil quando você precisa impor contratos de dados rigorosos na camada de API. Para cargas de trabalho em produção, você pode substituir a integração mock por uma função Lambda ou endpoint HTTP mantendo o mesmo modelo de validação.

Leitura Adicional




Mantenha-se Conectado

Se este artigo foi útil e você quer aprender mais sobre AWS, arquitetura de nuvem, IA, infraestrutura como código e segurança em nuvem, siga o autor para conteúdos e tutoriais futuros:
Fique ligado para mais tutoriais práticos e soluções para desafios de infraestrutura em nuvem e DevOps.
Boas construções na AWS!
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article