API REST CRUD completa con Spring Boot, JPA y validación

Un CRUD de clientes de principio a fin, con las piezas del curso en su lugar: entidad, record validado, repositorio, servicio transaccional y controlador, y cada error con su código. Es la plantilla de la que parte la mayoría de las APIs reales.

Lo que necesitas

Un proyecto de start.spring.io con Spring Web, Spring Data JPA, Validation y H2 Database. Para producción, cambia H2 por PostgreSQL o MySQL como en la lección 5. En application.properties:

spring.application.name=clientes
spring.jpa.open-in-view=false
spring.mvc.problemdetails.enabled=true

problemdetails.enabled hace que los errores salgan en el formato estándar ProblemDetail (RFC 9457); open-in-view=false evita una trampa que explicamos en las rarezas.

Las cuatro capas

Un CRUD (crear, leer, actualizar y borrar) bien hecho separa responsabilidades: la entidad es la tabla, el record es lo que manda el cliente, el repositorio habla con la base y el servicio decide las reglas. El controlador solo traduce HTTP.

package com.ejemplo.clientes;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;

@Entity
public class Cliente {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String nombre;
    @Column(unique = true)
    private String correo;
    private String ciudad;

    protected Cliente() {
    }

    public Cliente(String nombre, String correo, String ciudad) {
        actualizar(nombre, correo, ciudad);
    }

    public void actualizar(String nombre, String correo, String ciudad) {
        this.nombre = nombre;
        this.correo = correo;
        this.ciudad = ciudad;
    }

    public Long getId() { return id; }
    public String getNombre() { return nombre; }
    public String getCorreo() { return correo; }
    public String getCiudad() { return ciudad; }
}

El correo es único en la tabla. Los cambios pasan por un método, actualizar, en vez de setters sueltos.

package com.ejemplo.clientes;

import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public record DatosCliente(
        @NotBlank @Size(max = 100) String nombre,
        @NotBlank @Email String correo,
        @Size(max = 60) String ciudad) {
}

El record trae las reglas de validación. Separarlo de la entidad impide que el cliente mande un id o cualquier campo interno que no debería tocar.

package com.ejemplo.clientes;

import java.util.List;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ClienteRepository extends JpaRepository<Cliente, Long> {

    boolean existsByCorreo(String correo);

    List<Cliente> findByCiudadOrderByNombre(String ciudad);
}
package com.ejemplo.clientes;

import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.web.server.ResponseStatusException;

@Service
@Transactional
public class ClienteService {

    private final ClienteRepository repo;

    public ClienteService(ClienteRepository repo) {
        this.repo = repo;
    }

    @Transactional(readOnly = true)
    public List<Cliente> listar(String ciudad) {
        return ciudad == null ? repo.findAll() : repo.findByCiudadOrderByNombre(ciudad);
    }

    @Transactional(readOnly = true)
    public Cliente buscar(long id) {
        return repo.findById(id).orElseThrow(() ->
                new ResponseStatusException(HttpStatus.NOT_FOUND, "No existe el cliente " + id));
    }

    public Cliente crear(DatosCliente d) {
        if (repo.existsByCorreo(d.correo())) {
            throw new ResponseStatusException(HttpStatus.CONFLICT, "Ya hay un cliente con el correo " + d.correo());
        }
        return repo.save(new Cliente(d.nombre(), d.correo(), d.ciudad()));
    }

    public Cliente actualizar(long id, DatosCliente d) {
        Cliente c = buscar(id);
        c.actualizar(d.nombre(), d.correo(), d.ciudad());
        return c;
    }

    public void borrar(long id) {
        repo.delete(buscar(id));
    }
}

@Transactional en la clase aplica a todos sus métodos públicos; los de lectura llevan readOnly = true, que le permite a Hibernate ahorrarse revisar cambios. ResponseStatusException es la forma más corta de responder un error con su código: con ProblemDetail encendido, su mensaje sale en el campo detail. En actualizar no hay save: la entidad la cargó la transacción y Hibernate guarda los cambios al terminar.

package com.ejemplo.clientes;

import jakarta.validation.Valid;
import java.net.URI;
import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/clientes")
public class ClienteController {

    private final ClienteService servicio;

    public ClienteController(ClienteService servicio) {
        this.servicio = servicio;
    }

    @GetMapping
    public List<Cliente> listar(@RequestParam(required = false) String ciudad) {
        return servicio.listar(ciudad);
    }

    @GetMapping("/{id}")
    public Cliente uno(@PathVariable long id) {
        return servicio.buscar(id);
    }

    @PostMapping
    public ResponseEntity<Cliente> crear(@Valid @RequestBody DatosCliente datos) {
        Cliente c = servicio.crear(datos);
        return ResponseEntity.created(URI.create("/clientes/" + c.getId())).body(c);
    }

    @PutMapping("/{id}")
    public Cliente actualizar(@PathVariable long id, @Valid @RequestBody DatosCliente datos) {
        return servicio.actualizar(id, datos);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> borrar(@PathVariable long id) {
        servicio.borrar(id);
        return ResponseEntity.noContent().build();
    }
}

Probarlo

terminal$ curl -s -X POST localhost:8080/clientes -H "Content-Type: application/json" -d '{"nombre":"Ana López","correo":"ana@ejemplo.com","ciudad":"Puebla"}'
{"nombre":"Ana López","correo":"ana@ejemplo.com","ciudad":"Puebla","id":1}
$ curl -s -X POST localhost:8080/clientes -H "Content-Type: application/json" -d '{"nombre":"Luis Pérez","correo":"luis@ejemplo.com","ciudad":"Mérida"}'
{"nombre":"Luis Pérez","correo":"luis@ejemplo.com","ciudad":"Mérida","id":2}
$ curl -s -X POST localhost:8080/clientes -H "Content-Type: application/json" -d '{"nombre":"Sofía Ruiz","correo":"sofia@ejemplo.com","ciudad":"Puebla"}'
{"nombre":"Sofía Ruiz","correo":"sofia@ejemplo.com","ciudad":"Puebla","id":3}
$ curl -s localhost:8080/clientes?ciudad=Puebla
[{"nombre":"Ana López","correo":"ana@ejemplo.com","ciudad":"Puebla","id":1},{"nombre":"Sofía Ruiz","correo":"sofia@ejemplo.com","ciudad":"Puebla","id":3}]
$ curl -s -X PUT localhost:8080/clientes/2 -H "Content-Type: application/json" -d '{"nombre":"Luis Pérez","correo":"luis.perez@ejemplo.com","ciudad":"Mérida"}'
{"nombre":"Luis Pérez","correo":"luis.perez@ejemplo.com","ciudad":"Mérida","id":2}
$ curl -s -o /dev/null -w "%{http_code}\n" -X DELETE localhost:8080/clientes/3
204
$ curl -s localhost:8080/clientes
[{"nombre":"Ana López","correo":"ana@ejemplo.com","ciudad":"Puebla","id":1},{"nombre":"Luis Pérez","correo":"luis.perez@ejemplo.com","ciudad":"Mérida","id":2}]

Tres altas, un filtro por ciudad, un cambio de correo, un borrado (204) y la lista final. Ahora los errores:

terminal$ curl -s -X POST localhost:8080/clientes -H "Content-Type: application/json" -d '{"nombre":"Otra Ana","correo":"ana@ejemplo.com","ciudad":"León"}'
{"detail":"Ya hay un cliente con el correo ana@ejemplo.com","status":409,"title":"Conflict"}
$ curl -s -X POST localhost:8080/clientes -H "Content-Type: application/json" -d '{"nombre":"","correo":"no-es-correo","ciudad":"León"}'
{"detail":"Invalid request content.","status":400,"title":"Bad Request"}
$ curl -s localhost:8080/clientes/3
{"detail":"No existe el cliente 3","status":404,"title":"Not Found"}

El correo repetido da 409 Conflict con el mensaje del servicio; los datos inválidos, 400 (para devolver la lista de campos con su error, mira el manejador de la lección 6); y el cliente borrado, 404. Todos con el mismo formato.

¿Y si dos peticiones dan de alta el mismo correo al mismo tiempo? Las dos podrían pasar el existsByCorreo antes de que la otra guarde. Por eso el correo también es unique en la tabla: la base rechaza el segundo insert. La revisión del servicio da un mensaje amable en el caso normal; la restricción de la base es la que garantiza la regla.

Cada proyecto de esta página se compiló con Spring Boot 4.2.0, Java 25 (Temurin 25.0.5.1) y Maven 3.10.1 en un contenedor limpio y sin red, se arrancó y se probó con las peticiones de curl que ves; las respuestas y los registros están copiados de esa ejecución.