Parte 3 — Validación y contrato#
Desde comprobar un campo hasta publicar una API que no rompe a quien la consume.
Clases 39 a 50 · 12 en total · 12 construidas · 12 tecnologías en juego.
🧭 De qué va esta parte#
Una API es una promesa. Doce clases sobre cómo se escribe esa promesa, cómo se comprueba y cómo se cambia sin romper a quien confiaba en ella.
Empieza por lo evidente —validar lo que entra— y llega a lo que casi nadie hace bien: publicar el error con una forma estándar, derivar la documentación del código en lugar de escribirla aparte, y versionar sin abandonar a los clientes anteriores.
Es la parte donde el tipado deja de ser una preferencia estética y se convierte en infraestructura: un esquema bien escrito valida la entrada, genera la documentación y tipa el código, y las tres cosas no pueden discrepar.
🎒 Qué da por sabido#
- Las partes 1 y 2: códigos de estado, cuerpo JSON y capas transversales.
- Que el contrato se escribe antes que las implementaciones (clase 003).
🎯 Qué sabrás hacer al terminarla#
- Validar una entrada devolviendo todos los errores por campo, no el primero.
- Responder con
application/problem+jsonsegún RFC 9457, y explicar por qué un «datos inválidos» impide construir una interfaz accesible. - Escribir un esquema una vez y usarlo para validar, documentar y tipar.
- Paginar por desplazamiento y por cursor, y decir cuándo cada uno es el correcto.
- Hacer idempotente una operación que no lo es por naturaleza, y saber por qué eso es la condición para poder reintentar.
- Distinguir un cambio compatible de uno que rompe, y publicar el segundo sin coordinar despliegues.
🧵 Por qué en este orden#
Las cuatro primeras construyen la validación: rechazar (039), informar bien (040), declarar la forma (041) y reutilizar esa declaración (042).
Las cuatro siguientes son la vida pública de la API: documentarla (043), versionarla (044), paginarla (045) y filtrarla (046).
Las cuatro últimas son sobre confianza: idempotencia (047), caché condicional (048), el contrato como prueba (049) y qué rompe a quién (050).
📚 Las clases#
| # | Clase | Qué resuelve | Nivel | Estado |
|---|---|---|---|---|
| 039 | Validar la entrada | Rechazar lo inválido antes de que llegue a la lógica. | 🟢 introductorio | ✅ Construida |
| 040 | Errores por campo con RFC 9457 | Decir exactamente qué campo falló y por qué, en formato estándar. | 🟡 intermedio | ✅ Construida |
| 041 | Esquemas | Declarar la forma de los datos en lugar de comprobarla a mano. | 🟡 intermedio | ✅ Construida |
| 042 | Un esquema, tres usos | Derivar validación, tipos y documentación de una sola declaración. | 🟡 intermedio | ✅ Construida |
| 043 | Documentación generada | Publicar una descripción de la API que no puede mentir. | 🟡 intermedio | ✅ Construida |
| 044 | Versionado de API | Evolucionar sin romper a quien ya te consume. | 🔴 avanzado | ✅ Construida |
| 045 | Paginación | Devolver muchos elementos sin devolverlos todos. | 🟡 intermedio | ✅ Construida |
| 046 | Filtrado y ordenación | Aceptar criterios del cliente sin abrir un agujero. | 🟡 intermedio | ✅ Construida |
| 047 | Idempotencia | Hacer que reintentar no duplique. | 🔴 avanzado | ✅ Construida |
| 048 | ETags y caché condicional | Ahorrar ancho de banda y evitar sobrescrituras ciegas. | 🔴 avanzado | ✅ Construida |
| 049 | El contrato como prueba | Ejecutar la misma batería contra cualquier implementación. | 🟡 intermedio | ✅ Construida |
| 050 | Qué rompe a quién | Clasificar un cambio como compatible o incompatible antes de publicarlo. | 🔴 avanzado | ✅ Construida |
🎬 Las tecnologías que aparecen#
Entre paréntesis, en cuántas clases de esta parte interviene cada una. Estar aquí no es una recomendación: es que el problema de esa clase existe de verdad para esa tecnología.
| Ecosistema | Tecnologías |
|---|---|
| Python | FastAPI (12), Django (1), Flask (1) |
| Node.js | Express (11), Fastify (1) |
| .NET | ASP.NET Core (12) |
| JVM | Spring Boot (12) |
| Bun/TypeScript | Elysia (1) |
| Go | Gin (1) |
| PHP | Laravel (1) |
| Node.js/TypeScript | NestJS (1) |
| Ruby | Ruby on Rails (1) |
📖 Las palabras que esta parte define#
Validación · RFC 9457 · Esquema · OpenAPI · Versionado de API · Paginación · Filtrado · Idempotencia · Caché condicional · Cambio incompatible
Todas, con su definición, en el glosario.
✅ Cómo se ejecuta una clase de esta parte#
node scripts/run-class.mjs 039El verificador arranca cada implementación, la somete a su contrato.json y declara cuáles omitió por no encontrar su cadena de herramientas. Si te faltan cadenas, node scripts/doctor.mjs dice cuáles y cómo se instalan.
➡️ Y después#
La parte 4 baja al almacenamiento: de escribir SQL a mano a un dominio que no sabe que existe una base de datos.