El CRUD completo

Tres horas. Media hora para decidir qué valida cada ruta y qué código devuelve, y dos horas y media implementando las cinco operaciones de tu recurso según el contrato de ayer.

Se explica

25 minutos · conceptos y demostración

Hoy se implementa el contrato de ayer. Todo lo que aparece se reduce a dos preguntas que se repiten en cada ruta: qué entra y quién lo comprueba, y qué código dice lo que ha pasado.

Leer: la ruta recoge, el servicio decide

export async function listarProductos(peticion, respuesta, next) {
  try {
    const { categoria, max, orden, q } = peticion.query;
    const productos = await servicio.listar({ categoria, max, orden, busqueda: q });
    respuesta.json(productos);
  } catch (error) {
    next(error);
  }
}

La ruta no filtra: recoge los parámetros y se los pasa al servicio. Las funciones que hacen el trabajo son las de la UD3, que no saben nada de HTTP, y por eso las mismas sirven aquí y en el CLI.

Los parámetros de la consulta llegan como texto, igual que en la UD4:

const maximo = max === undefined ? null : Number(max);
if (maximo !== null && (Number.isNaN(maximo) || maximo < 0)) {
  throw new ErrorDeValidacion([{ campo: "max", mensaje: "Debe ser un número no negativo" }]);
}

En la obtención por identificador conviven los dos errores del contrato, dentro del mismo try que delega en next:

const id = Number(peticion.params.id);
if (!Number.isInteger(id) || id < 1) {
  throw new ErrorDeValidacion([{ campo: "id", mensaje: "Debe ser un entero positivo" }]);
}

const producto = await servicio.obtener(id);
if (!producto) throw new ErrorNoEncontrado("Producto no encontrado");

Una función decide, por último, qué sale, en lugar de devolver el objeto tal como está guardado:

function aRespuesta({ id, nombre, precio, categoria, stock }) {
  return { id, nombre, precio, categoria, disponible: stock > 0 };
}

Devolver el objeto en su forma almacenada resulta inmediato y expone información que no corresponde publicar: notas internas, márgenes o el propio stock. Una función que decide la forma pública del recurso deja explícito qué sale, y evita que añadir un campo interno lo publique sin querer.

Crear: la validación, en tres pasos

const CAMPOS_PERMITIDOS = ["nombre", "precio", "categoria", "stock", "descripcion"];

export function validarProductoNuevo(cuerpo) {
  if (cuerpo === null || typeof cuerpo !== "object" || Array.isArray(cuerpo)) {
    throw new ErrorDeValidacion([{ campo: "cuerpo", mensaje: "Se esperaba un objeto JSON" }]);
  }

  const errores = [];
  const limpio = {};

  // 1 · solo lo permitido entra
  for (const campo of CAMPOS_PERMITIDOS) {
    if (cuerpo[campo] !== undefined) limpio[campo] = cuerpo[campo];
  }

  // 2 · obligatorios y tipos
  if (typeof limpio.nombre !== "string" || limpio.nombre.trim() === "") {
    errores.push({ campo: "nombre", mensaje: "Es obligatorio" });
  }
  const precio = Number(limpio.precio);
  if (Number.isNaN(precio) || precio <= 0) {
    errores.push({ campo: "precio", mensaje: "Debe ser un número mayor que cero" });
  }

  // 3 · todos los errores a la vez
  if (errores.length > 0) throw new ErrorDeValidacion(errores);

  return { ...limpio, nombre: limpio.nombre.trim(), precio };
}

La respuesta incluye el recurso creado y la cabecera Location con su URL, porque quien crea no elige el identificador: lo asigna el servidor. Por eso id no está entre los campos permitidos.

const datos = validarProductoNuevo(peticion.body);   // lanza si no vale
const creado = await servicio.crear(datos);

respuesta
  .status(201)
  .location(`/api/productos/${creado.id}`)
  .json(aRespuesta(creado));

1. Nativa · comodidad
2. Cliente · buena experiencia
3. Servidor · la única obligatoria

Cualquiera puede llamar a tu API con un cliente HTTP y saltarse las dos primeras. Lo comprobarás hoy mismo.

Modificar y borrar

// PUT: lo que no llega, se pierde
const reemplazo = validarProductoNuevo(peticion.body);

// PATCH: se combina con lo que había
const cambios = validarCambios(peticion.body);      // ninguno obligatorio

El error clásico es implementar PUT combinando los campos: entonces tienes dos rutas que hacen lo mismo y un contrato que miente. Si solo vas a ofrecer una, ofrece PATCH y dilo en el contrato.

const borrado = await servicio.borrar(id);
if (!borrado) throw new ErrorNoEncontrado("Producto no encontrado");
respuesta.status(204).end();

Un 204 no lleva cuerpo: la operación ha ido bien y no hay nada que devolver. Sobre el segundo borrado existen dos posturas defendibles —404 porque ya no está, o 204 porque el resultado deseado se cumple— pero elige una y escríbela en el contrato.

Se trabaja

150 minutos · las cinco operaciones

Los tres primeros pasos implementan el contrato. Los dos últimos lo atacan: uno se salta tu propio cliente, y el otro comprueba la propiedad que permite reintentar sin miedo.

Paso 1 · Las lecturas completas · 35 min

1. Implementa la lista con filtro por categoría, texto y precio máximo.
2. Añade orden por dos campos, ascendente y descendente.
3. Implementa la obtención por identificador con sus dos errores.
4. Valida todos los parámetros y responde 400 con detalles.
5. Escribe la función que decide la forma pública del recurso, y comprueba que un campo interno nuevo no aparece en la respuesta.
6. Añade paginación con limite y pagina, devolviendo también el total.

Antes de continuar: ?categoria=inexistente devuelve 200 con lista vacía y ?max=abc devuelve 400. Si los dos dan lo mismo, la distinción no está hecha.

Paso 2 · La creación · 40 min

1. Implementa POST /api/productos con validación en tres pasos.
2. Devuelve 201, Location y el recurso creado.
3. Devuelve 400 con todos los errores, no solo el primero.
4. Descarta los campos no permitidos y demuéstralo enviando un id y un campo inventado.
5. Comprueba qué ocurre si el cuerpo no es JSON válido, y que da 400 y no 500.
6. Responde 409 si ya existe un producto con el mismo nombre.

Paso 3 · El CRUD cerrado · 40 min

1. Implementa PATCH con validación de los campos enviados, ninguno obligatorio.
2. Decide si ofreces PUT; si lo haces, que reemplace de verdad.
3. Implementa DELETE con 204 y su comportamiento documentado para el segundo borrado.
4. Añade una fecha de modificación que mantiene el servidor, no el cliente.
5. Impide modificar campos que el cliente no debería tocar, como el identificador o la fecha de creación.
6. Actualiza peticiones.http con todos los casos nuevos.

Paso 4 · Sáltate tu propio cliente · 20 min

Tu formulario de la UD4 valida. Comprueba qué pasa cuando alguien no lo usa: desde el fichero .http, envía estas peticiones directamente a la API.

Las dos últimas son las que se olvidan. Ninguna de las siete debe devolver 500, y ninguna debe llegar a escribir en el fichero de datos.

Escribe al terminar, en una línea, qué habría pasado si tu única validación fuera la del formulario.

Paso 5 · Repetir sin consecuencias · 15 min

1. Ejecuta dos veces seguidas el mismo PATCH. Compara el recurso después de la primera y de la segunda.
2. Ejecuta dos veces el mismo DELETE. Anota qué responde cada una.
3. Ejecuta dos veces el mismo POST. Cuenta los productos.
4. Rellena la tabla con lo observado y compárala con la del contrato de la sesión 1.

5. Explica en dos líneas por qué esa propiedad importa cuando la red falla y el cliente reintenta.

Ampliación si has completado el trabajo

Primero termina y comprueba los cinco pasos. El primer reto convierte la validación en dato; el segundo resuelve la carrera que arrastras desde la UD5.

Reto 1 · Las reglas de validación, como tabla

Tu validarProductoNuevo tiene las reglas escritas a mano. Con dos recursos más, serán tres funciones casi idénticas.

const ESQUEMA_PRODUCTO = {
  nombre:      { tipo: "texto",  obligatorio: true,  minimo: 2, maximo: 120 },
  precio:      { tipo: "numero", obligatorio: true,  minimo: 0.01 },
  categoria:   { tipo: "texto",  obligatorio: true,  valores: ["teclados", "ratones"] },
  stock:       { tipo: "entero", obligatorio: false, minimo: 0, porDefecto: 0 },
  descripcion: { tipo: "texto",  obligatorio: false, maximo: 500 }
};

1. Escribe validar(cuerpo, esquema) que recorra el esquema, aplique cada regla y devuelva los datos limpios o lance con todos los errores.
2. Que la lista blanca salga del propio esquema: lo que no esté declarado, se descarta.
3. Aplica los valores por defecto de los campos opcionales ausentes.
4. Escribe un segundo esquema para PATCH, donde nada sea obligatorio, derivándolo del primero en lugar de repetirlo.
5. Añade un tipo nuevo —fecha— sin tocar la función validar. Si has tenido que tocarla, el diseño no era genérico.
6. Escribe el esquema del segundo recurso de tu API y comprueba que la misma función sirve. Anota en tres líneas qué has ganado y qué has perdido respecto a los if escritos a mano: hay una pérdida real y conviene nombrarla.

Reto 2 · Dos clientes que se pisan

Reproduce la carrera de la UD5, ahora con dos peticiones HTTP en lugar de dos procesos.

1. Pide el mismo producto desde dos clientes. Los dos tienen ahora la misma versión.
2. Desde el primero, envía un PATCH que cambie el precio. Desde el segundo, sin volver a leer, envía otro que cambie el stock.
3. Consulta el producto. Uno de los dos cambios ha desaparecido. Explica exactamente por qué, siguiendo el orden de lectura y escritura.
4. Añade al recurso un campo de versión que el servidor incrementa en cada modificación y devuelve en cada lectura.
5. Haz que PATCH exija esa versión y responda 409 si no coincide con la actual. Decide si va en el cuerpo o en una cabecera, y busca cuál es la cabecera estándar para esto.
6. Repite el apartado 2 con la protección puesta. El segundo cliente debe recibir un 409, y su mensaje debe decirle qué hacer: volver a leer y reintentar.
7. Explica en tres líneas por qué esta estrategia se llama optimista, y cuál sería la alternativa pesimista. La segunda es la que verás en el módulo de servidor.

Cierre

5 minutos · comprobación y recuerdo

Ver respuestas

1 · Un 400 el primero, porque el parámetro está mal formado; un 200 con lista vacía el segundo, porque la petición era válida.

2 · Para no publicar campos internos al añadirlos al modelo.

3 · Enumerar los campos que se aceptan y descartar el resto; evita que quien llama introduzca campos no previstos.

4 · Un 201 con Location y el recurso creado.

5 · Con PUT los campos que no llegan se pierden; con PATCH se conservan.

6 · Que la segunda escritura pise a la primera sin que nadie lo note, salvo que haya una versión que lo detecte.

---