APIs OpenAPI-first para prototipos desordenados: mantente sincronizado

Por qué los prototipos se desmoronan cuando la API no está definida

La mayoría de los prototipos empiezan priorizando la velocidad: una pantalla, un endpoint, un cambio rápido. Luego la API sigue cambiando sin un registro claro de lo que debería aceptar y devolver. Se renombra endpoints, aparecen y desaparecen parámetros de consulta, y las formas de respuesta cambian según quien tocó el código por última vez.

El frontend suele rellenar huecos adivinando. Alguien codifica un nombre de campo que funcionó ayer. Otro añade un parámetro opcional más. El backend empieza a devolver silenciosamente un formato de error distinto. Nada parece roto en aislamiento, pero el sistema se vuelve frágil con rapidez.

Las pequeñas descoincidencias se convierten en grandes bugs porque permanecen ocultas hasta el peor momento. Un campo requerido pasa a opcional y el checkout se rompe. Una respuesta cambia de userId a id y la interfaz muestra espacios en blanco. Un booleano se convierte en string y la validación pasa en un lugar pero falla en otro. Las cabeceras de auth difieren entre endpoints y los usuarios reciben cierres de sesión aleatorios. Las respuestas de error varían, así que la UI no puede mostrar el mensaje correcto.

Una “única fuente de verdad” arregla esto día a día: una descripción acordada de cada endpoint (ruta, método, params, body de la petición, forma de la respuesta, formato de error) que frontend y backend siguen. Cuando esa fuente cambia, todos lo ven y actualizan juntos. Esa es la promesa detrás de las APIs OpenAPI-first.

No necesitas una reescritura completa para llegar ahí. Incluso un prototipo desordenado generado por IA puede mejorar paso a paso: documenta los endpoints que la gente usa realmente, fija las formas que importan y luego arregla el código para que coincida.

Qué significa realmente “OpenAPI-first”

OpenAPI es un contrato escrito para tu API. Normalmente es un archivo YAML o JSON que describe endpoints, entradas y salidas de una manera que tanto humanos como herramientas pueden leer. En lugar de depender de “funcionó ayer”, puedes señalar un documento y decir: esto es la verdad.

OpenAPI-first significa que el contrato se decide primero y luego el código lo sigue.

Con “spec last”, los equipos construyen endpoints rápido, el frontend adivina formas y todos parchean cuando algo se rompe. Más tarde, alguien documenta lo que existe, pero la documentación va retrasada y la deriva se vuelve normal.

Con “spec first”, se acuerdan los comportamientos desde el principio, aunque el backend siga siendo desordenado. El spec se convierte en el plan: qué debe llamar el frontend, qué debe devolver el backend y qué ocurre cuando fallan las cosas.

Un spec útil hace cuatro cosas sin ambigüedades:

• Endpoints y métodos: rutas, verbos HTTP, parámetros y un par de ejemplos.
• Reglas de auth: cómo se autentican los usuarios, qué headers o tokens se requieren y qué ocurre cuando falla la auth.
• Esquemas de datos: campos exactos para peticiones y respuestas (tipos, obligatorio vs opcional, formatos).
• Errores: formas estándar de error y códigos de estado, para que las fallas sean previsibles.

El beneficio práctico es la alineación. El backend implementa según el spec. El frontend puede generar tipos y llamadas que coincidan. QA prueba contra él. Producto puede leerlo y confirmar que la API soporta flujos reales.

Esto importa aún más para prototipos creados por IA donde los endpoints “más o menos” existen pero no son consistentes. Una ruta devuelve { user: ... }, otra devuelve { data: { user: ... } }, y los errores pueden ser texto plano en un sitio y JSON en otro. Escribir un contrato consistente obliga a tomar esas decisiones abiertamente y evita las conjeturas.

Cómo crear tu primer spec OpenAPI desde un prototipo desordenado

Los prototipos desordenados suelen tener una API, solo que no escrita. Tu primer spec debe describir lo que el sistema hace hoy y luego hacerse más consistente en cada pasada. La meta es el progreso, no la perfección.

Empieza recopilando evidencia de lo que ya existe: rutas del backend, llamadas de red del frontend, logs del servidor y cualquier nota o captura de pantalla. En bases de código generadas por IA (desde herramientas como Bolt, v0, Cursor o Replit), a menudo encontrarás endpoints que funcionan para una pantalla y fallan en uso real: checks de auth faltantes, nombres de campo extraños, errores inconsistentes. Captura requests y responses reales, aunque sean feos.

Elige primero un flujo estrecho para no intentar abordarlo todo. Una buena porción es algo que el negocio necesita, como “registro + crear proyecto” o “checkout + confirmación de pago”. Si puedes describir un flujo de extremo a extremo, tendrás un spec que puedes usar de inmediato.

Antes de escribir endpoints, establece unas reglas simples que prevengan caos futuro. Decide estilo de ruta (como /projects/{projectId}), convención de nombres (camelCase o snake_case), un patrón de paginación, una forma de error compartida y requisitos de auth claros por endpoint.

Ahora escribe la versión 0.1 del spec, aunque esté incompleta. Documenta los campos de los que estás seguro y usa descripciones para señalar incertidumbres. La mayor ganancia es dejar explícitos bodies de petición y respuestas, porque ahí es donde el frontend más adivina.

Un enfoque práctico: toma una respuesta real de los logs, úsala para redactar un esquema y luego quita los campos que no quieras garantizar a largo plazo.

Finalmente, haz una revisión rápida con las personas que tocan ambos lados: quien controla las llamadas del frontend y quien maneja los handlers del backend. Una pasada corta suele detectar códigos de estado desajustados, campos requeridos faltantes y confusión de nombres.

Genera clientes tipados para que el frontend deje de adivinar

Un cliente tipado es una pequeña librería generada desde tu spec OpenAPI que ya conoce endpoints, parámetros y formas de respuesta. En lugar de que el frontend adivine lo que devuelve el backend (y se lleve sorpresas en producción), tu editor puede avisarte en cuanto uses la API de forma incorrecta.

En la práctica, esto reemplaza llamadas fetch escritas a mano por un flujo repetible: genera el cliente desde el spec, importa las funciones y tipos generados y actualiza la UI para usarlos. Luego corrige errores de tipo inmediatamente en vez de depurar 400s después.

Los tipos detectan problemas comunes temprano: campos obligatorios faltantes, valores enum incorrectos y nombres desajustados (snake_case vs camelCase). También ayudan con datos complicados como fechas. Si la API dice que un campo es un string date-time, puedes manejarlo consistentemente en vez de convertirlo de forma distinta en cada parte de la UI.

Los tipos no bastan por sí mismos. Las apps reales aún necesitan comportamiento en tiempo de ejecución: timeouts para que la UI no se quede colgada, reintentos para redes inestables e inyección de tokens de auth para que cada request esté firmada igual. Un patrón sólido es configurar una instancia del cliente con estas reglas y usarla en todas partes.

Una regla debería ser innegociable: la generación del cliente es un paso del build, no un evento puntual. Si el spec cambia, el cliente debe regenerarse en el mismo commit, o la deriva vuelve.

Valida solicitudes y respuestas para detectar la deriva pronto

El código tipado ayuda a escribir las formas correctas, pero no puede proteger tu API cuando llega tráfico real. Las comprobaciones de tipo ocurren en build time. La validación en tiempo de ejecución sucede cuando el servidor recibe una petición o envía una respuesta. Sin ella, los clientes pueden enviar campos faltantes, formatos erróneos o datos extra y el backend podría aceptarlo por accidente.

Con APIs OpenAPI-first, el spec es el contrato. La validación en tiempo de ejecución es cómo haces cumplir ese contrato cada día, incluso cuando el código cambia rápido.

Valida las peticiones entrantes (y falla rápido)

Empieza por comprobar lo básico en cada endpoint. Quieres errores claros en vez de coerción silenciosa: campos obligatorios, formatos (emails, UUIDs, fechas, URLs), valores permitidos (enums) y cómo manejas campos inesperados (rechazar o eliminar). Pon límites sensatos en el tamaño del payload por seguridad.

Un bug común en prototipos desordenados: el frontend envía userId como número en un lugar y como string en otro. Los tipos podrían no detectarlo si partes de la app fueron generadas o editadas por separado. La validación en tiempo de ejecución lo detecta en la primera request mala y te dice exactamente qué falló.

Valida las respuestas salientes (para que el backend no derive)

La validación de respuestas es donde se esconde la deriva. Un refactor del backend cambia totalCount a total, o empieza a devolver null donde el spec dice string. La UI se rompe de formas que parecen aleatorias.

Validar respuestas obliga al servidor a mantenerse honesto: si devuelve algo fuera del spec, lo ves de inmediato en logs y tests.

También estandariza las respuestas de error para que la UI las pueda manejar sin casos especiales. Mantén una forma única en todo: un code estable (legible por máquina), un message corto (legible por humanos), details opcionales (errores de campo) y un traceId de request para soporte.

Mantén frontend y backend alineados durante los cambios

Cuando una API cambia, el mayor riesgo no es el cambio en sí. Es la descoincidencia silenciosa: el frontend sigue enviando la forma antigua, el backend espera la nueva y el bug solo aparece en producción.

Trata el spec como el apretón de manos entre equipos. Si el apretón cambia, todos ajustan la mano antes de seguir.

Un flujo simple previene la deriva:

• Actualiza primero el spec OpenAPI (request, response, errores).
• Regenera el cliente tipado y los tipos.
• Implementa el cambio del backend para que coincida con el spec.
• Actualiza el frontend usando los tipos regenerados.
• Ejecuta validación y tests antes de mergear.

Ese orden fuerza a que los desacuerdos aparezcan temprano, cuando el cambio aún es pequeño.

Los cambios rompientes ocurrirán. El problema son los cambios rompientes sin advertencia. Si necesitas renombrar un campo, cambiar un parámetro requerido o alterar el comportamiento, considera lanzar una nueva versión y mantener la antigua viva brevemente para que el frontend tenga una ventana segura para migrar. Para endpoints y campos que van a desaparecer, márcalos como deprecados en el spec y pon una fecha real de eliminación; si no, las deprecaciones tienden a quedarse para siempre.

Una lista corta de “hecho” ayuda a evitar cambios a medias:

• Spec actualizado (incluidos casos de error).
• Cliente tipado regenerado y comprometido.
• Compatibilidad hacia atrás verificada (o versión incrementada).
• Ítems deprecados marcados y rastreados.
• Tests de QA actualizados desde el spec.

Errores comunes que hacen fallar OpenAPI-first

Las APIs OpenAPI-first funcionan cuando el spec se trata como un artefacto real de producto, no como un archivo que está en el repo. La mayoría de los fracasos ocurren cuando los equipos adoptan herramientas (generadores, docs, mocks) pero evitan la parte difícil: acordar un contrato claro y hacerlo cumplir.

Una trampa común es mezclar estilos. Empiezas con rutas ordenadas y luego añades un endpoint que acepta un blob suelto de JSON porque el prototipo lo necesita hoy. Una semana después, la mitad de la API está limpia y la otra mitad es ad hoc, así que los clientes tipados o se rompen o acaban llenos de any.

Otro problema es saltarse los casos de error. Si el spec solo describe caminos felices, la UI no tiene forma fiable de manejar fallos. Terminas con lógica frágil como “si el mensaje incluye…” y un montón de estados UI únicos.

La auth también suele quedar vaga. Los prototipos tienen un bypass hardcodeado, un token pegado en localStorage o un flujo OAuth a medias. Si el spec no expone esquemas de seguridad y headers requeridos temprano, frontend y backend construyen supuestos distintos y la depuración se vuelve conjetural.

La generación de clientes puede volverse un evento puntual también. Los equipos generan un cliente tipado una vez y luego siguen cambiando el backend sin regenerarlo. El cliente deja de coincidir con la realidad y los desarrolladores empiezan a eludir errores de tipo en vez de arreglar el contrato.

Por último, muchos equipos tratan el spec solo como documentación. Si los servidores no validan requests y responses contra él (aunque sea en dev o staging), el spec se convierte en una lista de deseos. El contrato real pasa a ser lo que el backend devuelve hoy.

Una prueba simple: si un dev del frontend dice “lo intento y veo qué devuelve”, no estás usando el spec como contrato.

Chequeos rápidos antes de declarar una API “estable”

“Estable” no significa “perfecta”. Significa que la gente puede construir sobre ella sin adivinar, y los cambios son deliberados en vez de accidentales.

Empieza con una pregunta básica: ¿hay exactamente un spec que todos consideran la verdad? Si el backend tiene un archivo, el frontend otro y un contratista tiene una tercera copia en un hilo de chat, no tienes una API estable. Tienes tres opiniones.

Luego, comprueba la cobertura. Un spec puede estar bien escrito y aun así ser inútil si omite el viaje principal. Elige un flujo principal (registro, login, crear el objeto principal, listarlo, actualizarlo) y confirma que cada llamada en ese flujo esté documentada.

Estos chequeos atrapan la mayoría de los problemas de “funcionó en mi máquina”:

• Un archivo OpenAPI compartido se usa para generación de código y revisión, no se copia por ahí.
• Los esquemas marcan claramente qué es obligatorio, qué puede ser null y qué se puede omitir.
• Los errores son predecibles: misma forma, mismo nombre y códigos de estado que reflejan la realidad.
• Puedes regenerar clientes tipados y ejecutar validación de requests/responses con un comando repetible.
• El spec coincide con el comportamiento en producción para los endpoints principales, no solo con tests locales.

Cuidado con que “opcional” se convierta en cajón de sastre. Si un campo es verdaderamente opcional, explica qué ocurre cuando falta. Si es obligatorio para que una pantalla funcione, márcalo como requerido.

Un ejemplo que aparece en prototipos: devolver 200 con { "error": "Not logged in" } cuando falla la auth. Parece conveniente, pero rompe la generación de clientes tipados y empuja el manejo de errores a chequeos aleatorios en el frontend. Una API estable devuelve un claro 401 con un objeto de error consistente.

Un ejemplo realista: limpiar la API de un prototipo creado por IA

Imagina un prototipo generado por una herramienta de IA: tiene una página de login, una pantalla de perfil y una de pagos. En una demo se ve bien, pero al intentar usuarios reales aparecen las grietas.

El mayor problema es la descoincidencia. El frontend espera campos que el backend nunca envía porque ambos lados se construyeron copiando suposiciones. La UI de perfil renderiza displayName y plan, pero el backend devuelve name y nunca envía datos de suscripción. Mientras tanto, la pantalla de pagos envía { amount: "20", currency: "usd" }, pero el servidor solo acepta un entero amountCents y rechaza códigos de moneda en minúsculas.

Las APIs OpenAPI-first solucionan esto haciendo un contrato claro y luego obligando a ambos lados a cumplirlo.

Comienza pequeño: define solo los endpoints que la app usa hoy e incluye tanto respuestas de éxito como de error para que la UI no tenga que adivinar. Incluso un spec pequeño fuerza decisiones importantes: ¿plan es requerido? ¿Es free | pro? ¿Cómo se ve “no logueado” en JSON?

Una vez que el spec existe, genera un cliente tipado y reemplaza las llamadas fetch() escritas a mano. Si la UI intenta leer displayName pero el spec dice name, falla en compilación en vez de fallar a los usuarios.

Luego añade validación de requests en el backend. Cuando la pantalla de pagos envía { amount: "20" } en vez de { amountCents: 2000 }, el servidor lo rechaza inmediatamente con un 400 legible, no con un crash vago más adelante.

Siguientes pasos: convierte el spec en un proceso de desarrollo más tranquilo

No necesitas reescribir todo tu sistema para obtener valor con OpenAPI-first. La victoria más rápida es elegir un flujo que los usuarios toquen todos los días y hacerlo predecible de extremo a extremo.

Elige un flujo único y de mucho tráfico y publica un spec para él esta semana. Buenos candidatos son login, checkout o “crear ítem” más “listar ítems”. Mantén la primera versión pequeña pero completa: bodies de petición claros, respuestas claras y casos de error reales.

Luego usa el spec para evitar que la deriva vuelva: regenera el cliente tipado para ese slice, valida requests y responses para los mismos endpoints y haz del “no cambiar la API sin cambiar el spec” una costumbre.

Si la base de código ya está enmarañada (auth rota, secretos expuestos, endpoints espagueti, huecos de seguridad), una auditoría rápida te ayuda a evitar estandarizar un contrato malo. FixMyMess (fixmymess.ai) se centra en reparar apps generadas por IA y puede ayudar a convertir un prototipo con deriva en una API lista para producción bloqueando el contrato, arreglando el código para que coincida y endureciendo las áreas más riesgosas.