Deja de Adivinar Tu API: React con Contrato Primero usando OpenAPI

Pregunta rápida. ¿Cuántos de ustedes han tenido un error en el front-end que resultó ser un campo renombrado en el backend del que nadie les informó? Sí, de eso se trata esta charla para solucionar. Soy Violina, y durante los próximos minutos, quiero mostrarles cómo en Click My Horse TV dejamos de adivinar nuestra API y qué pasó con nuestro equipo, nuestras aplicaciones, e incluso nuestra fuerza laboral de IA cuando lo hicimos. Vamos a ello.

Construimos un sistema que funcionaba. React en la web, React Native en móvil, un backend, usuarios reales. Por la mayoría de las medidas, estaba bien. Y luego, lentamente, no lo estaba. No porque algo se rompiera, sino porque nunca estuvo del todo alineado. Y con el tiempo, esa desalineación se acumuló en algo que no podíamos ignorar. Esta es la historia de lo que encontramos, lo que hicimos al respecto, y lo que desbloqueó, incluyendo algunas cosas que no esperábamos.

Aquí está la configuración. React en el frontend web, hablando con una API web. React Native, hablando con una API móvil. Dos equipos, dos backends, un producto. Todos tienen una propiedad clara. No hay estado compartido para interferir entre ellos. Ciclos de lanzamiento independientes. Dibujamos esto en una pizarra en los primeros días, y tenía sentido. Recuerdo pensar, esto es limpio. Así es como escalas un equipo. En papel, esto parecía perfectamente razonable. El problema con sistemas como este es que la pizarra nunca te muestra lo que sucede tres años después. Dos equipos, mismo dominio de producto. APIs evolucionando independientemente. Esa combinación es donde comienza. Cada ingeniero toma decisiones locales razonables. Nombras un campo de la manera que tiene sentido para ti. Estructuras una respuesta de la manera que tu modelo de datos sugiere. Marcas algo como opcional, porque podría no estar siempre allí.

Ninguna de esas decisiones es incorrecta de forma aislada. Pero con los años, las decisiones razonables de cada equipo se suman a dos sistemas que ya no hablan el mismo idioma. Nadie lo planeó. Nadie se dio cuenta de que estaba sucediendo. Simplemente se acumuló.

Años después, comenzamos a encontrar cosas como esta. Web API, título, elementos. Mobile API, encabezado, componentes. La misma característica, los mismos datos subyacentes, pero dos formas completamente diferentes saliendo de dos puntos finales diferentes.

Y aquí está la cuestión. Ningún lado estaba equivocado. Ambos funcionan perfectamente para su propia plataforma. Pero en el momento en que necesitas compartir lógica o hacer referencia cruzada de comportamiento, o incorporar a alguien nuevo en ambas, te encuentras con la brecha.

Cada vez, era una sorpresa. Cada vez, costaba tiempo. Y cada vez, lo parcheábamos y seguíamos adelante porque aún no entendíamos lo que realmente estábamos viendo.

Estábamos viendo la Deriva, mismo dominio, diferentes formas. Los costos no aparecen en tus registros de errores. Aparecen en tu calendario. Un desajuste en tiempo de ejecución que tomó tres días rastrear porque no fue un fallo.

Simplemente eran datos incorrectos renderizados silenciosamente en la pantalla. Interfaces TypeScript duplicadas a través de proyectos, divergiendo lentamente de maneras que nadie rastreaba. Cada característica multiplataforma requiriendo una reunión de coordinación antes de que alguien escribiera una línea de código.

Un nuevo ingeniero pasando sus primeras dos semanas solo tratando de entender por qué el mismo concepto tenía un nombre diferente en cada lugar que miraban. Nada de esto se sentía catastrófico. Simplemente se sentía lento. La velocidad se ralentizó no por la complejidad, sino por la desalineación.

El ejemplo más claro de esa desalineación es toda nuestra aplicación móvil. La API no solo devolvía datos. Devolvía decisiones de UI. Y nada de esto fue malicioso. Evolucionó de esa manera porque no había un acuerdo compartido sobre cuál era realmente el trabajo de una API.

En ausencia de un contrato, la API se convierte en lo que el cliente pide en el momento. Y luego se queda así para siempre. Cada pantalla era un array de descriptores de componentes que el backend devolvía. Tipo header con ranuras izquierda, medio, derecha. Tipo linear player. Tipo navigation card list.

El backend necesitaba qué renderizar, decidía qué renderizar, en qué orden, en qué disposición. El frontend era un motor de renderizado, nada más. Una vez que tienes un patrón así en toda una aplicación, las consecuencias son predecibles. Acoplamiento estrecho. Frontend y backend bloqueados en una dependencia estructural, ningún equipo puede cambiar de manera independiente.

Casi imposible de probar. ¿Cómo pruebas unitariamente un componente cuyo diseño es determinado en tiempo de ejecución por un servicio remoto? Parálisis de refactorización. Y la dinámica del equipo donde cada pregunta de producto eventualmente se convierte en una pregunta de backend. Estaba claro que este no era un problema móvil. Este era un problema de contrato. Así que hicimos lo que los ingenieros hacen cuando algo no funciona. Buscamos lo que teníamos.

Colecciones de Postman, dos versiones principales detrás de la realidad, un catálogo de eventos de cliente interno que alguien había comenzado con buenas intenciones y abandonado silenciosamente. Ingenieros que genuinamente sabían cómo funcionaban las cosas. Algunos de ellos ya se habían ido. No teníamos una fuente de verdad compartida. Reflexiona sobre eso por un segundo. La deriva, la UI impulsada por el backend, las sesiones de depuración de tres días. Ninguno de esos eran problemas separados. Todos eran el mismo problema.

Porque cuando la verdad vive en la mente de las personas, vive cuando ellos lo hacen. Nuestro primer instinto es que, y sospecho que es uno familiar, fue escribir mejores tipos. Si el problema es que el frontend no sabe lo que devuelve la API, simplemente escribiremos mejores interfaces de TypeScript, más completas, más cuidadosamente mantenidas, más disciplinadas. Lo intentamos. No se sostuvo. Los tipos escritos a mano son solo tan precisos como la última vez que alguien recordó actualizarlos.

El momento en que el backend cambia algo y el frontend no sabe que el tipo está en vivo, compilan, pasan CI, y luego entregan silenciosamente datos incorrectos a tus usuarios. Así que intentamos documentación. Entradas más ricas en nuestro catálogo de eventos interno. Colecciones de Postman anotadas, un canal de Slack para cambios de API tampoco se sostuvo. La documentación es una descripción de lo que existe en el momento de escribir. Para cuando la lees, ya está ligeramente incorrecta, y no puedes hacerla cumplir. No puedes compilar contra una entrada del catálogo de eventos. No puedes escribir una prueba que falle cuando la documentación está desactualizada. Lo que realmente necesitábamos era algo legible por máquina, algo que no te dijera qué era la API, algo que generara el código que de otro modo escribirías a mano y rompiera la construcción cuando la realidad divergiera del spec.

Necesitábamos un contrato que las herramientas pudieran leer, no solo los humanos. OpenAPI, no como documentación, como la fuente. La mayoría de ustedes probablemente han encontrado OpenAPI a través de Swagger. Esa página de documentación interactiva que tu backend genera. La abres, encuentras el endpoint que necesitas, expandes el esquema de respuesta, tal vez haces clic en probarlo, es útil. Es mejor que nada. Pero eso es documentación, y las documentaciones como acabamos de establecer el caso.

Aquí está el cambio mental que lo cambió todo para nosotros. OpenAPI no es un formato de documentación. Es un formato de contrato. Hay una diferencia. Cuando escribes status string en tu interfaz de TypeScript, estás adivinando. Estás diciendo, creo que este campo existe. Creo que es string. Creo que estos son los valores posibles. Pero no estoy seguro, y nada me dirá si estoy equivocado. Cuando status está definido en un spec de OpenAPI, como un enum, con tres valores específicos, eso es una especificación.

El backend tiene que implementarlo. El frontend genera el tipo a partir de él. Si el spec dice active, maintenance, o closed, esos son los únicos valores válidos, y tu TypeScript lo sabe. Tu IDE lo sabe, y tu CI lo sabe. La documentación te dice lo que existe. Una especificación define lo que debe existir, y críticamente, permite que las herramientas lo hagan cumplir. Aquí es donde se vuelve práctico. Escribes tu práctico. Escribes tu OpenAPI YAML. Ejecutas un comando. ¿Qué sale? Tipos de TypeScript. Exactos, generados, nunca escritos a mano. Un cliente API tipado para web.

El mismo cliente para React Native desde la misma especificación. Formas de respuesta simuladas para tus pruebas, tipo contra el mismo contrato que usa tu código de producción. Las herramientas que hacen esto. Hey API te da tipos más un cliente SDK completo de un solo golpe. Orville genera hooks de consulta no-stack directamente desde la especificación. OpenAPI TypeScript es la opción mínima. Solo tipos, sin otras opiniones.

Cuando la especificación cambia, regeneras. TypeScript te dice inmediatamente dónde se rompieron las cosas, en ambas bases de código, antes de que confirmes, antes de que abras una solicitud de extracción, antes de que algo llegue a producción. Dejas de escribir código API. Lo generas. Contrato primero significa que la especificación no es algo que escribes después de que la característica está construida. Es cómo comienza la característica. Un ticket se recoge antes de que alguien escriba un manejador o un componente, alguien abre el archivo de especificación y define la forma del API.

Esa definición es revelada por backend, por frontend, por quien la consuma. Se fusiona. Luego la implementación comienza en ambos lados simultáneamente contra el mismo contrato acordado. El contrato no es un subproducto del desarrollo. Es la entrada a él. Ya no está en la cabeza de alguien o enterrado en nuestro catálogo de eventos. Está en el repositorio, versionado, revelable y aplicado. En términos concretos, cuatro cosas cambiaron. Primero, el API fue definido en OpenAPI antes de que cualquier implementación comenzara. La especificación era la fuente, no el resultado. Segundo, los clientes de TypeScript fueron generados tanto para web como para móvil desde esa única especificación. No escritos, no mantenidos, derivados.

Cada vez que la especificación cambiaba, regenerábamos. Tercero, el backend se implementó contra la misma especificación que consumía el frontend. Por primera vez, ambos lados trabajaban desde el mismo documento. Cuarto, los desajustes de contrato rompían las compilaciones en lugar de la producción. Un campo renombrado aparecía como un error de tipo en CI. Nota el informe de error de un usuario a las 11 PM.

Frontend y backend ahora comparten el mismo contrato antes de que se escribiera una sola línea de código de aplicación. Así es como se ve esto en la práctica. Defines un evento en vivo en la especificación. ID, nombre, país, código, evento de parada de emergencia son obligatorios. La URL de la imagen y el inicio de la próxima competencia son opcionales.

Stream es un array de streams de eventos en vivo. El generador se ejecuta y produce una interfaz de TypeScript. No aproximadamente correcta, sino exactamente correcta. Los mismos campos, los mismos tipos, las mismas restricciones de opcionalidad. En el lado del consumidor, usa la consulta de eventos en vivo tipada contra la interfaz generada. Tu ID sabe qué está disponible, cómo funciona completar.

Intentas renderizar la URL de la imagen directamente y TypeScript te recuerda que podría ser nuevo. Y si alguien en el backend renombró name a event name, regenera el cliente y abre el par, el error de TypeScript aparece inmediatamente en ambas bases de código. Ese es el momento que has estado depurando manualmente durante años. Ahora es automático. La especificación es donde vive la verdad. Todo lo que deriva de ella es solo un artefacto derivado.

Y esta es la especificación en sí. Evento en vivo en YAML. ID es un entero, name y country code son cadenas. E-stop event es un Booleano. Image URL y next competition start at son nuevos. Stream es un array. Cada elemento hace referencia al esquema del flujo de eventos en vivo. Este es el archivo que vive en tu repositorio. Esto es lo que entra en la revisión de código. Esto es lo que tiene un historial de Git. Cuando el equipo de backend necesita cambiar esto, lo cambian aquí primero.

La pull request es un cambio de especificación antes de que sea un cambio de código. Ambos lados lo ven, ambos lados están de acuerdo antes de que alguien implemente. El frontend ya no refleja el backend manualmente. Se compila contra él. Reflejar es frágil. Depende de que las personas se mantengan sincronizadas.

La compilación es obligatoria. Depende del sistema de tipos. La arquitectura resultante, esquema en la parte superior, web, backend y móvil apuntando todos al mismo esquema. También unificamos el backend, pero el esquema es lo que refuerza la alineación, no la unificación. Un backend unificado sin esquema aún puede desviarse. El esquema es la pieza de soporte.

Para ser concretos sobre lo que cambió y lo que no, todavía tenemos dos bases de código separadas, web y móvil. No las fusionamos. Permanecen independientes, desplegadas independientemente, propiedad independiente. ¿Qué cambió? Ahora consumen los mismos tipos generados de la misma especificación. Username en web y username en móvil, desaparecieron. ¿Qué cambió? Ahora consumen los mismos tipos generados de la misma especificación.

Username en web y username en móvil, desaparecieron. Una definición en la especificación, generada en ambos. Nombres de campos consistentes, formas consistentes, nueva habilidad consistente. Y cada frontend mantiene la propiedad total de su lógica de presentación. El backend devuelve datos de dominio. Qué hacer con esos datos, cómo presentarlos, qué mostrar, qué ocultar, eso permanece en el lado del frontend donde pertenece.

¿Recuerdas el ejemplo del principio, aquel donde la API devolvía instrucciones de diseño en lugar de datos? Una vez que tuvimos la especificación, teníamos algo que no teníamos antes. Una definición formal de para qué es un endpoint. Y cuando escribimos la especificación para esa pantalla móvil, fue inmediatamente obvio que la forma de la respuesta estaba equivocada. No sutilmente equivocada, obviamente equivocada. Codificaba el orden de toque, codificaba la visibilidad de la sección. Eso no son datos de API, eso es lógica de UI.

Volvimos, refactorizamos el endpoint durante varios sprints y el resultado fue una pantalla que el equipo de frontend poseía completamente. El backend devolvía los datos de dominio. El frontend decidía qué renderizar, en qué orden, bajo qué condiciones. La pantalla se volvió testeable sin simular un backend. Se convirtió en algo que el producto podía probar A-B sin un despliegue. El contrato no solo alineó los sistemas, hizo visibles los límites correctos.

Y una vez que puedes ver un límite incorrecto, puedes corregirlo. Ese cambio parece simple, pero es la diferencia entre una UI que puede ser probada independientemente desplegada e iterada por un equipo de producto, y una UI que requiere un ingeniero de backend en la sala para cada conversación de diseño. El contrato hizo explícito ese límite. No puedes accidentalmente poner lógica de diseño en un contrato de datos cuando el contrato es revisado por ambos equipos. Quiero hablar de algo interesante.

Una vez que tuvimos el esquema, comenzamos a obtener un valor real del desarrollo asistido por IA. Y no me refiero a que la IA escribió algún código repetitivo. Me refiero a que la salida fue precisa de una manera que no lo había sido antes. Antes de la migración del esquema, habíamos experimentado con herramientas de IA, le pedimos que generara hooks, componentes de scaffolding, escribiera casos de prueba. El código parecía correcto, era plausible, pero llamaba a endpoints que no existían. Inventaba nombres de campos, manejaba estados de error que no eran reales.

Después de la migración, comenzamos a alimentar la especificación de API abierta como contexto. Aquí está el contrato, genera el hook para este endpoint. La salida cambió, los nombres de los campos eran correctos, los tipos de retorno coincidían, el manejo de errores reflejaba lo que la API realmente devolvía. El modelo no mejoró, la entrada sí. La IA se volvió confiable porque el sistema estaba restringido. Eso no es una lección de ingeniería de prompts, es una lección de diseño de sistemas.

Si quieres una salida de IA confiable, dale una especificación precisa para trabajar. Concretamente, esto es lo que desbloqueó. Podíamos solicitar al modelo con la especificación para un endpoint y obtener un hook de React tipado que realmente funcionaba. No uno que parecía que funcionaba, uno que compilaba, coincidía con la API real y manejaba los campos correctamente. Podíamos generar mocks de prueba realistas a partir de la especificación, y debido a que los mocks provenían del mismo esquema que los tipos de producción, no podían desviarse.

Una respuesta simulada que no coincide con la forma real de la API es solo una prueba que te miente. Las nuestras no podían, la especificación lo impedía. Podíamos crear scaffolding de componentes que ya conocían la forma de los datos que habían consumido. El modelo no estaba adivinando la superficie de la API. La estaba leyendo.

La especificación no era solo un contrato entre nuestros sistemas. Se convirtió en el contexto que hacía que la automatización fuera confiable. La estructura hacía que la automatización fuera fiable. Ahora, ¿cómo llegas realmente aquí? Porque adoptOpenAPI es fácil de decir y difícil de comenzar. No hicimos una gran migración. No congelamos la hoja de ruta. Comenzamos con una regla, cualquier nuevo endpoint obtiene una especificación.

Eso es todo. El nuevo trabajo pasa por el esquema desde el primer día. Sin costo de migración, sin interrupciones, solo un punto de partida diferente para las cosas nuevas. A partir de ahí, gradualmente incorporamos endpoints existentes de alto impacto en la especificación, los que causaban más problemas, uno a la vez. Escribe la especificación, ejecuta el generador, reemplaza el código de obtención escrito a mano y el tipo escrito a mano, elimina el código antiguo, reducción neta de código cada vez.

Los enfoques antiguos y nuevos coexistieron sin fricciones. No hubo un cambio abrupto, ni una semana de congelación, solo un porcentaje creciente de la base de código que la especificación poseía. Y sucedió algo más que no anticipamos completamente. Frontend y backend ahora podían desarrollarse en paralelo en la misma característica. Backend implementando contra la especificación, frontend construyendo contra mocks generados derivados de la misma especificación. Ambos equipos trabajando desde el mismo contrato convergiendo en la misma forma de endpoint. La integración pasó de ser un proceso de una semana de descubrir desajustes a deshabilitar los mocks, ejecutar las pruebas, enviarlo, comenzar con un endpoint.

No voy a decirte que esto fue gratis. La primera conversación real que tuvimos fue sobre la propiedad. ¿Quién posee el archivo de especificación? ¿Quién tiene que aprobar un cambio en él? Si eso no está claro, la especificación se convierte en un punto de conflicto en lugar de un punto de alineación. Lo resolvimos haciendo del esquema un artefacto compartido. Cambios revelados por los equipos de backend y frontend juntos. Un proceso de aprobación, dos perspectivas. Mantener la especificación honesta es un trabajo continuo.

Si un ingeniero de backend envía un cambio de campo sin actualizar la especificación primero, la especificación miente. Y la especificación mentirosa es peor que ninguna especificación. Porque te da una falsa confianza. Implementamos verificaciones de CI. La especificación se valida contra la API en ejecución en cada fusión. Eso requirió inversión en herramientas. Valió la pena, pero no fue gratis. Las convenciones de nomenclatura, camel case o snake case parecen triviales hasta que tienes dos equipos con hábitos diferentes y una especificación que tiene que elegir uno. Tuvimos la conversación una vez, tomamos la decisión, lo escribimos en la especificación, hecho. Pero tuvimos que tenerla. Y algunos ingenieros de backend nunca habían pensado en su API como un contrato antes. Eso no es una crítica. Es solo un modelo mental diferente. Pasamos tiempo en ello. Todo eso fue un costo real. Nada de eso fue una razón para no hacerlo.

Quiero ser honesto sobre dónde esto vale la pena y dónde podría ser excesivo. Vale la pena la inversión cuando tienes múltiples clientes frontend consumiendo la misma API. Cuando el producto tiene una larga vida y la API será versionada y mantenida durante años. Cuando el equipo está creciendo y ya no puedes confiar en el contexto compartido. Cuando la complejidad del dominio está aumentando y la brecha entre lo que la API hace y lo que el frontend asume que hace se está volviendo más difícil de cerrar. Probablemente sea excesivo para un prototipo de cliente único que controlas de principio a fin. O un proyecto con una vida útil de seis semanas donde eres el único consumidor.

La pregunta a hacer es ¿cuánto nos cuesta la deriva de la API y está empeorando? Si la respuesta es sí, esta es la herramienta correcta. Así que seamos precisos sobre lo que realmente movió la aguja. Porque no fueron las herramientas. El generador de código es solo un mecanismo. Hey API, Orval, OpenAPI TypeScript, esos son solo programas. Hacen lo que les dices. Lo que redujo la profundidad fue la decisión que precedió a todos ellos. Un contrato compartido en el límite. Un lugar, un archivo, una fuente de verdad para la forma de cada interacción de API en todo el sistema.

Evolución explícita del esquema, lo que significa que no hay cambios silenciosos. Cada adopción de campo, cada cambio de nombre, cada duplicación pasa por la especificación primero. Se revela, se versiona, nada muta sin un registro. Desajustes de contrato rompiendo compilaciones en lugar de producción. Esa categoría de error, aquella donde un campo cambió y nadie le dijo al frontend, simplemente dejó de suceder. Y la clara separación de responsabilidades. Backend posee los datos del dominio. Frontend posee la presentación. La especificación es la línea entre ellos.

La profundidad técnica se acumula cuando los acuerdos implícitos decaen. Cada convención no documentada, cada suposición mantenida en la cabeza de alguien, todo lo que todos saben, todo eso es profundidad esperando ser llamada. El esquema hizo que nuestros acuerdos fueran explícitos, eso fue lo que detuvo la decadencia.

Cuatro cosas que me gustaría que te llevaras de esto. Trata la API como un producto. Tiene consumidores. Tiene un ciclo de vida. Sobrevivirá al sprint que la creó. Dale la misma disciplina de diseño que le das a tu UI. Intencional, versionada, poseída. Define el contrato antes de que comience la implementación. No como un paso de documentación después de que hayas terminado. Como lo que hace posible la implementación. Cambia lo que significa comenzar una característica para ambos equipos.

No dejes que tu backend tome decisiones de UI. Si la respuesta de tu API y los códigos disponen el orden de visibilidad, ese es un problema de contrato esperando convertirse en un problema de refactorización. La especificación hace visibles esos límites antes de que se calcifiquen. Y usa esquemas para potenciar tus herramientas. Todas ellas. Generadores de tipos, bibliotecas de simulación, asistentes de IA. Todos mejoran cuando el contrato es preciso y legible por máquina. El esquema es la entrada que hace que la automatización sea confiable. Comenzamos con dos frontends, dos backends y ningún acuerdo compartido sobre nada. Terminamos con dos frontends, un backend, un contrato. La alineación reemplazó la deriva. Mira este diagrama. React web y React native ambos apuntando a la misma especificación de API abierta. Ambos hablando con el mismo backend. Las flechas no son solo arquitectura. Son acuerdos.

Son la cosa que no tuvimos durante años. Finalmente escrito. El contrato es lo que te permite cambiar el nombre de un campo y saber inmediatamente qué se rompe. Es lo que permite a un nuevo ingeniero entender el sistema sin llamar a nadie. Es lo que permite a un asistente de IA generar código que realmente compila. Es lo que permite al equipo de backend implementar un cambio sin coordinarse primero con ambos equipos de frontend. El contrato se convirtió en el límite de confianza. La seguridad de tipos no se trata de tipos. Se trata de confianza entre sistemas. Gracias.