
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.
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
timestampcorrespondendo ao padrãoYYYY-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.

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.

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.

2.2 Entendendo o Modelo
O modelo impõe as seguintes regras:
- eventType (obrigatório): deve ser um dos valores
LOGIN,LOGOUTouPURCHASE
- 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.

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.

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.

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.

5.2 Configurar a Integration Response
5.2.1. Na aba Integration response, para a Default - Response, escolha Edit.

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.

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"}

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.

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.
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.
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"}

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"}

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
patterndo 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:
- LinkedIn: https://www.linkedin.com/in/biagolini
- Medium: https://medium.com/@biagolini
- GitHub: https://github.com/biagolini
- YouTube (PT-BR): https://www.youtube.com/@BiagoliniTech
- AWS Builder Center (PT-BR): https://builder.aws.com/community/@cbiagolini
Fique ligado para mais tutoriais práticos e soluções para desafios de infraestrutura em nuvem e DevOps.
Boas construções na AWS!
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article