Marc Semper Lloret
← Servidor web y API con Node

Sesión 2 · Semana 1

El contrato: rutas, códigos y formas

Hoy · Hoja de ruta

  1. 1. Aprende: Qué compone el contrato de una API y por qué no se rompe a la ligera.
  2. 2. Haz: Escribe el contrato completo de tu API antes de implementarlo.
  3. 3. Comprueba: Otra persona podría escribir el cliente solo con tu contrato.

Antes de empezar · 5 minutos, sin apuntes

  1. Si cambias el nombre de un campo de la respuesta, ¿qué se rompe?
  2. ¿Cómo sabría un cliente distinguir «no existe» de «se rompió»?
  3. ¿Qué debe devolver una creación correcta?

Lo que forma el contrato

Pieza Qué fija
Ruta y método Cómo se pide cada operación
Cuerpo de la petición Qué campos se envían y de qué tipo
Código de estado Qué ha pasado
Cuerpo de la respuesta Qué campos vuelven y con qué nombre
Formato de error La misma forma, siempre

La tabla de tu API

Método Ruta Éxito Errores
GET /api/productos 200 500
GET /api/productos/:id 200 400, 404
POST /api/productos 201 400
PUT /api/productos/:id 200 400, 404
PATCH /api/productos/:id 200 400, 404
DELETE /api/productos/:id 204 400, 404

El 400 de las rutas con identificador no es un capricho: /api/productos/abc es una petición mal formada, y responder 404 a eso confunde «no existe» con «no me has pedido bien».

El formato de error

{
  "error": "Los datos no son válidos",
  "codigo": "VALIDACION",
  "detalles": [
    { "campo": "precio", "mensaje": "Debe ser un número mayor que cero" },
    { "campo": "nombre", "mensaje": "Es obligatorio" }
  ]
}

Un solo formato de error, en toda la API

Si un error llega a veces como texto plano, a veces como { error } y a veces como { mensaje }, el cliente necesita un tratamiento distinto para cada ruta, y ninguno para las que todavía no existen.

Con una forma única, el cliente escribe una función de tratamiento de errores y vale para toda la API, hoy y cuando crezca. El campo codigo permite además reaccionar por programa sin depender del texto, que puede traducirse o reescribirse.

Métodos: qué se puede repetir

Método Repetirlo dos veces
GET No cambia nada
PUT Deja el mismo resultado
DELETE El segundo no borra nada nuevo
POST Crea otro

Esa propiedad —que repetir la operación no cambie el resultado— es la que permite que un cliente reintente sin miedo cuando la red falla. Con POST no se puede, y por eso los formularios que se envían dos veces crean dos pedidos.

Tarea 2 · El contrato escrito

  1. Escribe la tabla completa de tu API, con éxitos y errores por ruta.
  2. Define el objeto que representa un producto: campos, tipos y cuáles son obligatorios.
  3. Define el formato único de error, con sus códigos.
  4. Escribe peticiones.http con un ejemplo de cada caso, incluidos los que fallan.
  5. Dale el contrato a un compañero y que escriba, sobre papel, cómo llamaría a tres rutas.
Objetivo mínimoContrato completo y fichero de peticiones con todos los casos.
Si lo tienesAñade paginación al contrato y decide qué devuelve la respuesta.
RetoDocumenta qué cambiarías si mañana hiciera falta la versión 2 sin romper la 1.

Checkpoint · fin de la sesión 2

  • Tu contrato cubre método, ruta, cuerpo, estado y respuesta.
  • Todos los errores tienen la misma forma.
  • Distingues 400 de 404 en la misma ruta.
  • Sabes qué operaciones se pueden repetir sin consecuencias.

Antes de cerrar · 2 minutos, sin mirar

  1. ¿Qué código devuelve una creación correcta?
  2. ¿Qué responde /api/productos/abc?
  3. ¿Por qué un formato único de error facilita el cliente?
Ver respuestas

1 · Un 201, con la cabecera Location.

2 · Un 400: la petición está mal formada, no es que el recurso no exista.

3 · Porque permite escribir un solo tratamiento válido para toda la API.