Consumindo uma API REST com o Postman

Depois de construir uma API RESTful, o próximo passo é testá-la. O Postman é a ferramenta ideal para isso: permite disparar requisições HTTP, enviar corpos em JSON e inspecionar as respostas — tudo sem escrever uma linha de front-end. Neste artigo eu percorro a API Academia Digital, feita com Spring Boot, mostrando como consumir cada endpoint.

⚙️ Antes de começar

1. Suba a aplicação (AcademiaDigitalApplication) com o MySQL rodando.
2. Importe a coleção pronta no Postman: Import → File → academia-digital.postman_collection.json. A base URL fica na variável {{base_url}}.
3. Em toda requisição POST/PUT, configure o corpo em Body → raw → JSON — isso define o header Content-Type: application/json. Enviar como Text resulta em 415 Unsupported Media Type.
4. Datas sempre no formato brasileiro dd/MM/yyyy (ex.: 13/01/1994), graças aos deserializers customizados do projeto.

📌 Convenção de retornos HTTP

Os controllers retornam a entidade diretamente (sem ResponseEntity), então o Spring responde assim:

Não há 201 Created nem 404 Not Found — é o comportamento atual do projeto, mantido por consistência com o código base.

👤 Aluno — /alunos

1. Criar Aluno  POST

Rota /alunos — cria um aluno. O cpf é único, então use um CPF diferente a cada cadastro.

POST http://localhost:8081/alunos

{
    "nome": "Amanda",
    "cpf": "333.111.111-00",
    "dataDeNascimento": "13/01/1994",
    "bairro": "Nova Viçosa"
}

Retorno 200 OK: o aluno criado com o id gerado.

2. Listar Alunos  GET

Sem a query, retorna todos. Com ?dataDeNascimento=, filtra por data de nascimento (uso de Derived Query):

GET http://localhost:8081/alunos
GET http://localhost:8081/alunos?dataDeNascimento=13/01/1994

3. Buscar / 4. Atualizar / 5. Deletar

Buscar por id e deletar não têm corpo. O PUT atualiza o aluno — note que o cpf não é atualizável (não faz parte do AlunoUpdateForm):

GET    http://localhost:8081/alunos/1
DELETE http://localhost:8081/alunos/1

PUT    http://localhost:8081/alunos/1
{
    "nome": "Amanda Ribeiro",
    "dataDeNascimento": "13/01/1994",
    "bairro": "Boa Viagem"
}

Ao remover um aluno, suas avaliações físicas também são removidas em cascata (cascade = CascadeType.REMOVE).

🏋️ Avaliação Física — /avaliacoes

Criar uma avaliação exige um alunoId existente. O retorno traz o aluno aninhado e a dataDaAvaliacao preenchida automaticamente.

POST http://localhost:8081/avaliacoes

{
    "alunoId": 1,
    "peso": 80.5,
    "altura": 1.80
}

Atualizar envia apenas peso e altura. Listar e buscar por id seguem o mesmo padrão dos alunos.

📝 Matrícula — /matriculas

A matrícula é criada só com o alunoId. Ela não possui PUT — por design, é criada e removida, não editada.

POST http://localhost:8081/matriculas
{
    "alunoId": 1
}

GET http://localhost:8081/matriculas
GET http://localhost:8081/matriculas?bairro=Casa Forte   // filtra por bairro (Native Query)

🗂️ Tabela-resumo dos endpoints

✅ Conclusão

Com a coleção importada no Postman, testar a API vira questão de segundos: você dispara os endpoints, confere os status HTTP e valida os JSONs de retorno. Esse fluxo é essencial para garantir que a API se comporta como esperado antes de conectar qualquer front-end.