Um Endpoint, para seguir o padrão REST, deve retornar um código de resposta adequado ao processamento da requisição. Por exemplo, no caso da URL http://localhost:8080/medicos/id, o mais adequado seria retornar o código 204 - Mensagem processada e sem conteúdo.

Para padronizar e controlar as resposta dos Endpoints, é utilizado a classe ResponseEntity do Spring como retorno.

@DeleteMapping("/{id}")
@Transactional
public ResponseEntity excluir(@PathVariable Long id){
    var medico = medicoRepository.getReferenceById(id);
    medico.excluir();

    return ResponseEntity.noContent().build();
}

Assim como, o código para um cadastro é 201 - Created, devolvendo no corpo da resposta o dados do recurso/registro cadastrado, e também um cabeçalho do protocolo HTTP (Location).

@PostMapping
@Transactional
public ResponseEntity cadastrar(@RequestBody @Valid DadosCadastroMedico dados, UriComponentsBuilder uriBuilder){
    var medico = new Medico(dados);
    medicoRepository.save(medico);

    var uri = uriBuilder.path("/medicos/{id}").buildAndExpand(medico.getId()).toUri();

    return ResponseEntity.created(uri).body(new DadosDetalhamentoMedico(medico));
}

Categoria de códigos

Os códigos HTTP (ou HTTPS) possuem três dígitos, sendo que o primeiro dígito significa a classificação dentro das possíveis cinco categorias.

1XX: Informativo – a solicitação foi aceita ou o processo continua em andamento;

2XX: Confirmação – a ação foi concluída ou entendida;

3XX: Redirecionamento – indica que algo mais precisa ser feito ou precisou ser feito para completar a solicitação;

4XX: Erro do cliente – indica que a solicitação não pode ser concluída ou contém a sintaxe incorreta;

5XX: Erro no servidor – o servidor falhou ao concluir a solicitação.

O que foi aprendido?