Exemplo de uso do ResponseEntity no Spring Boot para retornar status HTTP e corpo da resposta em APIs REST
O ResponseEntity no Spring Boot é uma das classes mais importantes para criar
API REST em Java de forma profissional.
Neste artigo você vai entender o que é ResponseEntity, quando usar e ver exemplos práticos no dia a dia.
Essa é uma dúvida muito comum para quem já aprendeu
Controller vs RestController no Spring Boot
e quer evoluir na criação de APIs REST.
O que é ResponseEntity no Spring Boot?
O ResponseEntity é uma classe do Spring que representa uma resposta HTTP completa.
Com ela, você pode controlar:
- O corpo da resposta (body)
- O status HTTP
- Os headers
Isso torna o ResponseEntity Spring Boot ideal para APIs REST, onde o controle da resposta é fundamental.
Por que usar ResponseEntity em APIs REST?
Em uma api rest spring boot java, retornar apenas um objeto pode não ser suficiente.
Muitas vezes, você precisa informar se a requisição foi bem-sucedida, se ocorreu um erro ou se um recurso foi criado.
O ResponseEntity permite retornar respostas mais semânticas e alinhadas com o protocolo HTTP.
Exemplo simples de ResponseEntity no Spring Boot
@GetMapping("/usuarios")
public ResponseEntity<List<String>> listarUsuarios() {
List<String> usuarios = List.of("Ana", "Carlos", "João");
return ResponseEntity.ok(usuarios);
}
Nesse exemplo, o método retorna um ResponseEntity com status 200 OK
e uma lista no corpo da resposta.
ResponseEntity com status HTTP personalizado
Uma das maiores vantagens do ResponseEntity no Spring Boot é a possibilidade de definir explicitamente o status HTTP.
@PostMapping("/usuarios")
public ResponseEntity<String> criarUsuario() {
return ResponseEntity.status(HttpStatus.CREATED)
.body("Usuário criado com sucesso");
}
Aqui, o endpoint retorna o status 201 Created, que é o mais adequado para criação de recursos.
Quando NÃO usar ResponseEntity?
Nem sempre o uso de ResponseEntity é obrigatório.
- O retorno é simples e sempre será 200 OK
- Não há necessidade de headers personalizados
- O endpoint é apenas informativo
Mesmo assim, em APIs REST profissionais, o uso de ResponseEntity é considerado uma boa prática.
ResponseEntity vs retorno direto de objeto
Retorno direto
@GetMapping("/status")
public String status() {
return "API online";
}
Com ResponseEntity
@GetMapping("/status")
public ResponseEntity<String> status() {
return ResponseEntity.ok("API online");
}
O segundo exemplo deixa explícito o status HTTP retornado pela API.
ResponseEntity e Status HTTP
O ResponseEntity trabalha diretamente com os códigos de status HTTP, como:
- 200 OK
- 201 Created
- 204 No Content
- 400 Bad Request
- 404 Not Found
- 500 Internal Server Error
No próximo artigo, veremos em detalhes como usar corretamente os
status HTTP em APIs REST com Spring Boot
.
ResponseEntity funciona com RestController?
Sim. O ResponseEntity funciona perfeitamente com @RestController
e é amplamente utilizado em APIs REST modernas.
Essa combinação é a base para criar APIs limpas, previsíveis e fáceis de manter.
Conteúdos relacionados
Conclusão
O ResponseEntity no Spring Boot é uma ferramenta essencial para quem deseja criar APIs REST profissionais em Java.
Ele permite controlar status HTTP, corpo da resposta e headers, tornando sua API mais semântica, clara e alinhada com boas práticas.