Controladores Spring Boot e REST API com POST

No artigo anterior Controladores Spring Boot e REST API, aprendemos sobre Controladores Spring Boot e como criar um método interativo a partir de métodos de requisições GET.

Mas como ficaria o mesmo exemplo usando POST ao invés do GET?

Existem duas formas mais populares de manipular dados pelo método POST, a primeira mais simples é apenas substituir a anotação @GetMapping("...") por @PostMapping("...")    

Mas apenas substituir pode retornar um erro, portanto, recomendo que apague @GetMapping e digite @PostMapping no lugar para que a classe java seja devidamente importada;

Como Testar o método POST em um método controlador Spring Boot?

Até aqui, note que apenas substituímos a notação @GetMapping por @PostMapping e ao acessarmos a rota pelo navegador iremos no deparar com erro.

Nem todo erro é ruim, isso significa que estamos no caminho certo pois afinal de contas, o método GET não será mais executado, ao invés disso, o método esperado agora é um POST, portanto, manipular dados na URL do navegador não irá mais funcionar.

Testar o método POST com curl

A forma mais simples de testar um método POST, independente da linguagem de programação utilizada é pelo comando curl, que é padrão no sistemas Linux, mas também pode ser encontrado em algumas versões do Windows.

1. Inicie ou reinicie a sua aplicação Spting Boot. É importante que http://localhost:8080 esteja funcionando.
2. No VS Code, abra um novo terminal usando o atalho Ctrl + Shift + ‘ ou pelo menu Terminal > New Terminal.
3. Agora, execute o comando (tudo em uma linha só);
   
   curl.exe -X POST -d "num1=5&num2=10" http://localhost:8080/calculadora/somar
   
4. O resultado será uma saída JSON, semelhante a visualizada no navegador.
   

Aplicações RESTful usando @RequestBody

Embora o exemplo acima tenha funcionado perfeitamente, é importante entender que essa não é a forma mais usual de trabalhar com métodos POST em APIs RESTful.

O mais comum é encontrar códigos usando @RequestBody em vez de @RequestParam, pois, em APIs modernas, os dados geralmente são enviados no corpo da requisição em formato JSON, e não como parâmetros de formulário ou query string.

Portanto, para seguir as melhores práticas e garantir maior flexibilidade e compatibilidade com clientes diversos, recomenda-se usar @RequestBody para métodos POST que recebem dados estruturados.

Modifique o método Somar() da seguinte forma.

1. Substitua os parâmetros @RequestParam Integer num1, @RequestParam Integer num2 por @RequestBody Map<String, Integer> dados
   
   conforme imagem;
   
   
   
   
2. Finalmente, salve o arquivo e reinicie sua aplicação.
3. Teste a aplicação, no entanto, o comando curl mudou.
   
   No CMD utilize;
   curl.exe -X POST -H "Content-Type: application/json" -d "{\"num1\":5,\"num2\":10}" http://localhost:8080/calculadora/somar
   
   No Power Shell, é mais complicado pois temos que escapar as aspas;
   curl.exe -X POST -H "Content-Type: application/json" -d "{`"num1`":5,`"num2`":10}" http://localhost:8080/calculadora/somar
   
   
   

A extensão Simple REST Client do VS Code

Perceba que testar requisições POST diretamente na linha de comando pode ser um desafio. Uma forma bem mais prática de fazer isso é utilizar uma extensão chamada Simple REST Client.

Após instalada a extensão, você verá um ícone de um fogete, bastando clicar em “New Request”.

Agora, configure as requisições da seguinte forma;

Name: Dê um nome qualquer para a sua requisição, a boa notícia é que ela ficará salva.
URL: A endpoint + a rota para acessar o método controlador, como por exemplo: http://localhost:8080/calculadora/somar
Headers: Como estamos trabalhando com o padrão REST, é importante entender que os dados sempre são trocados no formado JSON, portando configure para { "Content-Type": "application/json" }
Method: POST (ou GET dependendo do teste que deseja fazer).
Options: Deixe vazio.
Body: Aqui você criar uma estrutura JSON contendo todos os dados que você deseja passar para o seu método controlador, por exemplo; { "num1": 5, "num2": 11}

Então eu posso utilizar @RequestParam ou @RequestBody?

Esta é uma discussão interessante, você certamente já deve ter ouvido a expressão ‘é errando que se aprende’. O primeiro exemplo usando @RequestParam funcionou, mas isso pode gerar confusão sobre as melhores práticas.

Mas por que funcionou? O Spring Boot é flexível e permite que métodos POST recebam parâmetros de formas diferentes, e isso gera a necessidade de padronizar para evitar que cada desenvolver programe cada um do seu jeito.

Usar @RequestParam em métodos POST quebra o padrão RESTful, pois:

1. Limita a flexibilidade dos dados (apenas tipos simples),
2. Não permite estruturas complexas (objetos aninhados, arrays, JSON),
3. Dificulta a documentação e manutenção da API,
4. Pode confundir outros desenvolvedores que esperam dados no corpo.

Considerando asmelhores práticas de desenvolvimento do RESTful, o correto é sempre utilizar @RequestBody para métodos do tipo POST e deixar o @RequestParam para métodos do tipo GET.