Controladores REST con Spring Boot: GET, POST, PUT y DELETE

Lección 3 de 8: controladores REST. En la lección 1 tu endpoint devolvía un texto; ahora vas a hacer una API de verdad, con un catálogo de productos que se puede leer, crear, cambiar y borrar, que habla en JSON y que responde con el código de estado correcto en cada caso. Es lo que hace la mayoría de las aplicaciones de Spring Boot en el mundo.

Qué es una API REST

Una API es una forma de que un programa le pida cosas a otro. Cuando la app de tu banco muestra tu saldo, por debajo hace una petición HTTP a un servidor, que responde con los datos en JSON, un formato de texto muy fácil de leer para cualquier lenguaje. Una API REST organiza esas peticiones alrededor de recursos (productos, clientes, pedidos), cada uno con su dirección, y usa los métodos de HTTP para decir qué hacer con ellos:

  • MétodoPara quéEjemplo
  • GETLeerGET /productos/2: dame el producto 2
  • POSTCrearPOST /productos con un JSON: guarda este producto nuevo
  • PUTReemplazarPUT /productos/2 con un JSON: así queda ahora el producto 2
  • PATCHCambiar una partePATCH /productos/2/existencias: ajusta solo las existencias
  • DELETEBorrarDELETE /productos/2

La respuesta siempre trae un código de estado, un número que resume qué pasó: los que empiezan con 2 son éxito (200 OK, 201 Created, 204 No Content), los que empiezan con 4 son errores de quien pidió (400 datos mal formados, 404 no existe, 405 método no permitido, 415 formato no soportado) y los que empiezan con 5 son errores del servidor.

Petición y respuesta. La petición lleva el método y la ruta, POST /productos, una cabecera Content-Type: application/json y un cuerpo con el JSON del producto. La respuesta lleva el código 201 Created, una cabecera Location: /productos/4 y el cuerpo con el producto ya guardado, con su id 4Petición y respuestapeticiónPOST /productosContent-Type: application/json{"nombre":"Audífonos", …}respuesta201 CreatedLocation: /productos/4{"id":4,"nombre":"Audífonos", …}
Lo que viaja en una petición POST y en su respuesta. Esquema: decodigo.com.

El proyecto: un catálogo en memoria

Crea en start.spring.io un proyecto catalogo con la dependencia Spring Web, como en la lección 1. Vamos a guardar los productos en un mapa en memoria; en la lección 5 los pasamos a una base de datos. Primero, el dato. Un record de Java es ideal: una clase inmutable que declara sus campos en una línea y trae constructor, equals, hashCode y toString hechos:

package com.ejemplo.catalogo;

import java.math.BigDecimal;

public record Producto(Long id, String nombre, BigDecimal precio, int existencias) {
}

El precio es BigDecimal y no double, porque con double las cuentas de dinero acumulan errores de redondeo. Después, el servicio, que guarda los productos y les asigna un número consecutivo. Es un bean con @Service, así que existe una sola copia que comparten todas las peticiones; por eso usa ConcurrentHashMap y AtomicLong, que aguantan que dos peticiones lleguen al mismo tiempo:

package com.ejemplo.catalogo;

import java.math.BigDecimal;
import java.util.Comparator;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.stereotype.Service;

@Service
public class ProductoService {

    private final Map<Long, Producto> productos = new ConcurrentHashMap<>();
    private final AtomicLong siguienteId = new AtomicLong();

    public ProductoService() {
        guardar(new Producto(null, "Teclado mecánico", new BigDecimal("1299.00"), 8));
        guardar(new Producto(null, "Mouse inalámbrico", new BigDecimal("349.50"), 25));
        guardar(new Producto(null, "Monitor 24 pulgadas", new BigDecimal("3299.00"), 4));
    }

    public List<Producto> todos() {
        return productos.values().stream().sorted(Comparator.comparing(Producto::id)).toList();
    }

    public Optional<Producto> buscar(long id) {
        return Optional.ofNullable(productos.get(id));
    }

    public Producto guardar(Producto p) {
        long id = p.id() != null ? p.id() : siguienteId.incrementAndGet();
        Producto conId = new Producto(id, p.nombre(), p.precio(), p.existencias());
        productos.put(id, conId);
        return conId;
    }

    public boolean borrar(long id) {
        return productos.remove(id) != null;
    }
}

El controlador

Y ahora la pieza nueva. Léela con calma; abajo explicamos cada anotación:

package com.ejemplo.catalogo;

import java.math.BigDecimal;
import java.net.URI;
import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/productos")
public class ProductoController {

    private final ProductoService servicio;

    public ProductoController(ProductoService servicio) {
        this.servicio = servicio;
    }

    @GetMapping
    public List<Producto> listar(@RequestParam(required = false) BigDecimal max) {
        if (max == null) return servicio.todos();
        return servicio.todos().stream().filter(p -> p.precio().compareTo(max) <= 0).toList();
    }

    @GetMapping("/{id}")
    public ResponseEntity<Producto> uno(@PathVariable long id) {
        return ResponseEntity.of(servicio.buscar(id));
    }

    @PostMapping
    public ResponseEntity<Producto> crear(@RequestBody Producto nuevo) {
        Producto guardado = servicio.guardar(
                new Producto(null, nuevo.nombre(), nuevo.precio(), nuevo.existencias()));
        return ResponseEntity.created(URI.create("/productos/" + guardado.id())).body(guardado);
    }

    @PutMapping("/{id}")
    public ResponseEntity<Producto> actualizar(@PathVariable long id, @RequestBody Producto cambios) {
        if (servicio.buscar(id).isEmpty()) return ResponseEntity.notFound().build();
        return ResponseEntity.ok(servicio.guardar(
                new Producto(id, cambios.nombre(), cambios.precio(), cambios.existencias())));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> borrar(@PathVariable long id) {
        return servicio.borrar(id) ? ResponseEntity.noContent().build() : ResponseEntity.notFound().build();
    }
}
El viaje de una petición GET /productos/2: la envía curl o el navegador; Tomcat la recibe en el puerto 8080; el DispatcherServlet de Spring busca el método que atiende esa ruta; tu método con @GetMapping devuelve un objeto Producto; y Jackson lo convierte en JSON. La respuesta regresa por el mismo caminoEl viaje de una peticióncurl o el navegadorGET /productos/2Tomcatrecibe la conexión en el puerto 8080DispatcherServletbusca el método que atiende la rutatu @GetMapping("/{id}")devuelve un objeto ProductoJacksonconvierte el objeto en JSONla respuesta regresa por el mismo camino
Lo que pasa entre que llega la petición y sale el JSON. Esquema: decodigo.com.
  • @RestController: la clase atiende peticiones, y lo que devuelven sus métodos se convierte en el cuerpo de la respuesta (en JSON, si es un objeto).
  • @RequestMapping("/productos") en la clase: todas sus rutas empiezan con /productos.
  • @GetMapping, @PostMapping, @PutMapping, @DeleteMapping: qué método HTTP y qué ruta atiende cada método de Java. Sin ruta, es la de la clase.
  • @PathVariable: toma un pedazo de la ruta. En /{id}, el 2 de /productos/2 llega como long id. Spring lo convierte solo.
  • @RequestParam: toma un parámetro de la dirección, lo que va después de ?. Con required = false es opcional y llega como null si no viene.
  • @RequestBody: el cuerpo de la petición, en JSON, se convierte en un objeto Producto. Jackson empata cada campo del JSON con el componente del record del mismo nombre.
  • ResponseEntity: cuando además del cuerpo quieres elegir el código o las cabeceras. ResponseEntity.of(optional) responde 200 con el producto o 404 si el Optional está vacío; created(uri) responde 201 con la cabecera Location; noContent(), 204 sin cuerpo.

Probarlo con curl

Arranca la aplicación con ./mvnw spring-boot:run y, en otra terminal, prueba cada método. La opción -i de curl muestra también el código y las cabeceras de la respuesta; -X elige el método, -H agrega una cabecera y -d manda un cuerpo:

terminal$ curl -s localhost:8080/productos
[{"id":1,"nombre":"Teclado mecánico","precio":1299.00,"existencias":8},{"id":2,"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25},{"id":3,"nombre":"Monitor 24 pulgadas","precio":3299.00,"existencias":4}]
$ curl -s localhost:8080/productos/2
{"id":2,"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25}
$ curl -i -s localhost:8080/productos/99
HTTP/1.1 404 
Content-Length: 0
Date: Sun, 22 Nov 2026 16:02:39 GMT

$ curl -s "localhost:8080/productos?max=1000"
[{"id":2,"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25}]

La lista sale como un arreglo JSON, en el orden de los ids. El producto 99 no existe, así que la respuesta es 404 sin cuerpo. Tomcat escribe solo el número en la primera línea (HTTP/1.1 404), sin la frase «Not Found»; es normal en HTTP/1.1 y los clientes se guían por el número. Fíjate en la cabecera Content-Type: application/json de las otras: Jackson convirtió los records y Spring avisa el formato. Ahora, crear, cambiar y borrar:

terminal$ curl -i -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"Audífonos","precio":899.90,"existencias":12}'
HTTP/1.1 201 
Location: /productos/4
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 22 Nov 2026 16:02:39 GMT

{"id":4,"nombre":"Audífonos","precio":899.90,"existencias":12}
$ curl -s -X PUT localhost:8080/productos/4 -H "Content-Type: application/json" -d '{"nombre":"Audífonos inalámbricos","precio":949.00,"existencias":10}'
{"id":4,"nombre":"Audífonos inalámbricos","precio":949.00,"existencias":10}
$ curl -i -s -X DELETE localhost:8080/productos/1
HTTP/1.1 204 
Date: Sun, 22 Nov 2026 16:02:39 GMT

$ curl -s localhost:8080/productos
[{"id":2,"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25},{"id":3,"nombre":"Monitor 24 pulgadas","precio":3299.00,"existencias":4},{"id":4,"nombre":"Audífonos inalámbricos","precio":949.00,"existencias":10}]

El POST respondió 201 Created con el producto ya guardado, con su id 4, y la cabecera Location dice dónde consultarlo. Así un cliente sabe la dirección del recurso nuevo sin adivinarla. El PUT reemplazó el producto completo; el DELETE respondió 204, que significa «hecho, y no hay nada que devolver». La última lista ya no trae el teclado.

El JSON en un archivo. Escribir JSON dentro de la orden es incómodo, sobre todo en Windows, donde las comillas se escapan distinto en cmd, en Windows PowerShell y en PowerShell 7. Lo más fácil en cualquier sistema es guardar el cuerpo en un archivo y mandarlo con -d @archivo:

curl -X POST localhost:8080/productos -H "Content-Type: application/json" -d @nuevo.json
terminal (nuevo.json trae una base para laptop de $459)$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d @nuevo.json
{"id":5,"nombre":"Base para laptop","precio":459,"existencias":6}

El error que te ahorra: olvidar la cabecera Content-Type

Sin -H "Content-Type: application/json", curl manda el cuerpo como si fuera un formulario web, y Spring no sabe convertir eso en un Producto:

terminal$ curl -i -s -X POST localhost:8080/productos -d '{"nombre":"Cable USB-C","precio":159}'
HTTP/1.1 415 
Accept: application/json, application/*+json
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sun, 22 Nov 2026 16:02:39 GMT

{"timestamp":"2026-11-22T16:02:39.311Z","status":415,"error":"Unsupported Media Type","path":"/productos"}

415 Unsupported Media Type: «no acepto ese formato». La cabecera Accept de la respuesta dice cuáles sí acepta. Cuando una petición que «debería funcionar» falla con 415, revisa primero esa cabecera, en curl, en Postman o en el código del cliente.

Otros errores que responde Spring por ti

No escribiste nada para estos casos y aun así cada uno tiene su código correcto. Pedir DELETE a la colección completa, que no tiene ese método, da 405; mandar texto donde va un número, 400:

terminal$ curl -s -X DELETE localhost:8080/productos
{"timestamp":"2026-11-22T16:02:39.331Z","status":405,"error":"Method Not Allowed","path":"/productos"}
$ curl -s -X POST localhost:8080/productos -H "Content-Type: application/json" -d '{"nombre":"Cable USB-C","precio":"barato"}'
{"timestamp":"2026-11-22T16:02:39.350Z","status":400,"error":"Bad Request","path":"/productos"}

El cuerpo de error de Spring es escueto a propósito: dice el código y la ruta, pero no por qué falló, para no revelar detalles internos a quien llama. En la lección 6 aprenderás a devolver errores claros, como «el precio debe ser mayor que cero», sin enseñar las tripas de la aplicación.

Ojo con la seguridad: no confíes en el id que manda el cliente

Fíjate en que crear ignora el id que venga en el JSON y arma un producto con null, y que actualizar usa el de la ruta, no el del cuerpo. Si usaras el objeto tal cual llega, alguien podría mandar un POST con "id":1 y pisar el producto 1. La regla general: lo que llega del cliente se revisa y se copia campo por campo a lo que guardas. En la lección 6 se agrega la validación de cada campo.

Retos

Reto 1. Agrega GET /productos/buscar?texto=..., que devuelva los productos cuyo nombre contenga el texto, sin importar mayúsculas. ¿Qué responde si no mandas texto?

Ver la solución
package com.ejemplo.catalogo;

import java.util.List;
import java.util.Locale;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class BusquedaController {

    private final ProductoService servicio;

    public BusquedaController(ProductoService servicio) {
        this.servicio = servicio;
    }

    @GetMapping("/productos/buscar")
    public List<Producto> buscar(@RequestParam String texto) {
        String buscado = texto.toLowerCase(Locale.ROOT);
        return servicio.todos().stream()
                .filter(p -> p.nombre().toLowerCase(Locale.ROOT).contains(buscado))
                .toList();
    }
}
terminal$ curl -s "localhost:8080/productos/buscar?texto=MOUSE"
[{"id":2,"nombre":"Mouse inalámbrico","precio":349.50,"existencias":25}]
$ curl -s "localhost:8080/productos/buscar?texto=silla"
[]
$ curl -s localhost:8080/productos/buscar
{"timestamp":"2026-11-22T16:02:39.163Z","status":400,"error":"Bad Request","path":"/productos/buscar"}

Un @RequestParam sin required = false es obligatorio: si falta, Spring responde 400 antes de llamar a tu método. Fíjate en que /productos/buscar no choca con /productos/{id}: Spring prefiere la ruta más específica, la que no tiene variables. Locale.ROOT hace que la conversión a minúsculas no dependa del idioma de la computadora.

Reto 2. Agrega PATCH /productos/{id}/existencias?cambio=N, que sume N (o reste, si es negativo) a las existencias. Si quedarían en negativo, responde 409 Conflict sin cambiar nada.

Ver la solución
package com.ejemplo.catalogo;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ExistenciasController {

    private final ProductoService servicio;

    public ExistenciasController(ProductoService servicio) {
        this.servicio = servicio;
    }

    @PatchMapping("/productos/{id}/existencias")
    public ResponseEntity<Producto> ajustar(@PathVariable long id, @RequestParam int cambio) {
        return servicio.buscar(id).map(p -> {
            int nuevas = p.existencias() + cambio;
            if (nuevas < 0) return ResponseEntity.status(HttpStatus.CONFLICT).body(p);
            return ResponseEntity.ok(servicio.guardar(new Producto(id, p.nombre(), p.precio(), nuevas)));
        }).orElse(ResponseEntity.notFound().build());
    }
}
terminal$ curl -s -X PATCH "localhost:8080/productos/3/existencias?cambio=-3"
{"id":3,"nombre":"Monitor 24 pulgadas","precio":3299.00,"existencias":1}
$ curl -s -w " (código %{http_code})\n" -X PATCH "localhost:8080/productos/3/existencias?cambio=-5"
{"id":3,"nombre":"Monitor 24 pulgadas","precio":3299.00,"existencias":1} (código 409)

El monitor tenía 4: tras restar 3 quedan 1, y restar 5 más daría -4, así que responde 409 con el producto sin cambios. La opción -w de curl imprime el código al final. map y orElse del Optional cubren el caso del id que no existe con 404.

Reto 3. ¿Por qué el POST responde 201 y no 200, si los dos significan «salió bien»? ¿Le importa a alguien?

Ver la solución

Sí importa: el código es parte del contrato de tu API. 201 dice «se creó algo nuevo», y junto con la cabecera Location le indica al cliente dónde está, sin que tenga que adivinar ni leer el cuerpo. Muchas bibliotecas de clientes, herramientas de pruebas y puertas de enlace de APIs reaccionan distinto a cada código. Responder siempre 200, incluso en los errores, es uno de los fallos de diseño más comunes, y obliga a quien usa la API a leer cada cuerpo para saber si funcionó.

Cada proyecto de esta lección 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 acceso a la red, se arrancó y se le hicieron las peticiones que ves con curl antes de publicar la lección; los registros, las respuestas y los errores están copiados de esa ejecución. Las horas de los registros son de la Ciudad de México.