APIs REST con Spring Boot y JPA paso a paso

Desarrollar APIs REST profesionales con Spring Boot y JPA no es cuestión de suerte: es cuestión de método. Si ya intentaste armar un CRUD y terminaste con un montón de archivos desordenados, entidades mal mapeadas y respuestas JSON inconsistentes, este tutorial paso a paso te va a mostrar el camino que usan los equipos que llevan proyectos a producción sin dolores de cabeza. Vamos directo al código, pero con criterio de arquitectura.

💼 Empleos tech relacionados:

• Desarrollador Java BackEnd | Híbrido |CDMX · Indra Group
• Desarrollador backend

3,340 vacantes activas en LATAM · ver todas → · ⭐ Opiniones en Google

🎓 Cursos confirmados con 50% OFF hoy para lectores del blog:

• 💬 Diplomado .NET Empresarial Desde Cero · Inicia 26 Sep · sabatino · $39,990 $19,995 (-50%) MXN
• 💬 Visual Studio .NET Desde Cero · Inicia 26 Sep · sabatino · $12,250 $6,125 (-50%) MXN
• 💬 Consultor AWS Despliegue de Apps · Inicia 28 Sep · lunes - jueves · $8,130 $4,065 (-50%) MXN

Por WhatsApp en horario habil · ver todos los cursos → · ⭐ Opiniones en Google

Prepara el entorno antes de escribir una sola línea

Muchos tutoriales arrancan generando el proyecto y luego explican el por qué. Aquí lo hacemos al revés: primero entiende las piezas, después las armas. Una API REST profesional con Spring Boot y JPA se apoya en cuatro pilares: Spring Web para exponer endpoints, Spring Data JPA para persistencia, un motor de base de datos (H2 en desarrollo, PostgreSQL o MySQL en producción) y Bean Validation para no confiar nunca en lo que llega del cliente.

Herramientas mínimas que necesitas tener listas:

• JDK 17 o superior (Spring Boot 3 lo exige).
• Maven o Gradle configurado en tu IDE.
• Spring Initializr para generar la estructura base.
• Postman, Insomnia o curl para probar cada endpoint.
• Un cliente de base de datos como DBeaver para inspeccionar tablas.

Si prefieres acelerar el aprendizaje con una ruta guiada en lugar de ir saltando entre documentación y foros, un curso de Spring Frameworks te ahorra semanas de prueba y error porque cubre desde la inyección de dependencias hasta patrones avanzados de persistencia.

Genera el proyecto con las dependencias correctas

En Spring Initializr selecciona Maven, Java 17 y agrega estas dependencias desde el primer momento: Spring Web, Spring Data JPA, Validation, H2 Database y Lombok (opcional pero cómodo). No agregues todo lo que aparece: cada dependencia extra es deuda técnica que luego alguien tendrá que mantener.

La estructura de paquetes que recomiendo para que tu API escale sin volverse un caos es por capas de dominio, no por tipo de archivo:

1. controller — expone los endpoints HTTP.
2. service — contiene la lógica de negocio y las transacciones.
3. repository — interfaces que extienden JpaRepository.
4. entity — clases mapeadas con @Entity.
5. dto — objetos de transferencia para entrada y salida.
6. exception — manejadores globales de errores.

Esta separación evita que tu controlador termine haciendo consultas SQL y que tu entidad se convierta en la respuesta JSON que ve el cliente. Ese es el error número uno de las APIs amateur.

Obtén descuentos exclusivos de nuestros cursos en vivo en línea

Capacítate con los expertos

Quiero recibir noticias

Por favor clic en quiero recibir noticias.

Email es requerido.

x

You Have Successfully Subscribed to the Newsletter

Modela entidades JPA sin romper el rendimiento

Una entidad no es una tabla con anotaciones. Es un objeto de dominio con reglas. Al definir tus clases con @Entity, cuida estos detalles que marcan la diferencia entre una API que responde en 50 ms y otra que tarda dos segundos:

• Usa @Id con @GeneratedValue(strategy = GenerationType.IDENTITY) para claves simples.
• Define relaciones @ManyToOne con fetch = FetchType.LAZY por defecto. El EAGER es la causa silenciosa del problema N+1.
• Marca @Column(nullable = false, length = 100) para que la base de datos también valide.
• Usa @Version si vas a manejar concurrencia optimista.
• Nunca expongas la entidad directamente: convierte a DTO en el servicio.

Sobre el problema N+1: ocurre cuando haces una consulta para traer una lista y luego Hibernate dispara una consulta adicional por cada elemento relacionado. Se soluciona con JOIN FETCH en JPQL o con @EntityGraph. Si no lo controlas, tu API se cae en producción cuando la tabla crece.

Construye el repositorio y el servicio con criterio

El repositorio extiende JpaRepository<Entidad, Long> y ya te da save, findById, findAll y deleteById. Pero para una API profesional necesitas consultas derivadas y JPQL personalizado:

public interface ProductoRepository extends JpaRepository<Producto, Long> {
    List<Producto> findByCategoriaNombre(String nombre);

    @Query("SELECT p FROM Producto p JOIN FETCH p.categoria WHERE p.precio > :min")
    List<Producto> findCarosConCategoria(@Param("min") BigDecimal min);
}

El servicio es donde vive la lógica. Anota la clase con @Service y los métodos de escritura con @Transactional. Ahí conviertes entidades a DTO, lanzas excepciones de negocio y aplicas reglas que no pertenecen ni al controlador ni a la base de datos.

Si quieres profundizar en cómo estructurar repositorios, transacciones y consultas eficientes, un taller práctico de API REST con Spring Boot y JPA te muestra exactamente estos patrones con ejercicios reales, no con ejemplos de juguete.

Expón los endpoints REST con buenas prácticas HTTP

El controlador no debe tener lógica. Solo recibe, delega y responde. Estas son las reglas que debes seguir sin excepción:

• @RestController y @RequestMapping("/api/v1/productos") para versionar desde el día uno.
• @PostMapping devuelve 201 Created con la URI del recurso creado.
• @GetMapping devuelve 200 OK con el recurso o la lista paginada.
• @PutMapping para reemplazo completo, @PatchMapping para actualización parcial.
• @DeleteMapping responde 204 No Content, nunca un JSON con «eliminado».
• Usa @Valid en los DTO de entrada para activar Bean Validation.

Para paginación, no devuelvas listas completas. Usa Pageable y Page<ProductoDTO>. Esa sola decisión te salva cuando la tabla tiene 500.000 registros.

Maneja errores con un @ControllerAdvice global

Una API profesional no devuelve stack traces al cliente. Crea una clase con @RestControllerAdvice que capture excepciones y las transforme en respuestas consistentes con código HTTP correcto y un cuerpo uniforme:

{
  "timestamp": "2025-01-15T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Producto con id 42 no existe",
  "path": "/api/v1/productos/42"
}

Captura al menos MethodArgumentNotValidException para errores de validación, EntityNotFoundException para recursos inexistentes y una excepción genérica para no filtrar detalles internos. Esto es lo que diferencia una API que otros equipos quieren consumir de una que nadie entiende.

Valida, documenta y prueba antes de publicar

El ciclo no termina cuando el endpoint responde. Termina cuando está probado y documentado. Tres pasos obligatorios:

1. Escribe pruebas de integración con @SpringBootTest y MockMvc para cada endpoint.
2. Documenta con Springdoc OpenAPI (Swagger UI) para que el frontend sepa qué esperar.
3. Revisa logs y tiempos de respuesta con Spring Boot Actuator.

Si además quieres exprimir el rendimiento de tu API, tienes una guía práctica sobre cómo optimizar APIs REST con Spring Boot y JPA que cubre cachés, consultas eficientes y ajustes de conexión. Aplicar esas técnicas después de tener la base sólida es lo que convierte un proyecto funcional en un proyecto profesional.

Checklist final para tu primera API lista para producción

• Entidades con relaciones LAZY y sin exponerse directamente.
• DTOs validados con Bean Validation.
• Servicios transaccionales y con lógica de negocio aislada.
• Controladores delgados y versionados.
• Manejo global de errores con códigos HTTP correctos.
• Paginación en todos los listados.
• Pruebas de integración y documentación OpenAPI.

Dominar Spring Boot y JPA no se logra leyendo, se logra construyendo. Toma este tutorial, arma tu API de principio a fin, rompe algo a propósito y arréglalo. Ahí es donde realmente aprendes. Y si quieres ir más rápido con acompañamiento estructurado, las rutas de TecGurus y los recursos de Programa en Línea que enlazamos arriba son un atajo legítimo para llegar a nivel profesional sin perder meses en el intento.

💼 Empleos tech relacionados:

• Desarrollador Java BackEnd | Híbrido |CDMX · Indra Group
• Desarrollador backend

3,340 vacantes activas en LATAM · ver todas → · ⭐ Opiniones en Google