Manejo de Cambios Significativos en GraphQL

Hola a todos, es un placer estar aquí y es un placer hablar sobre algo que es muy relevante para mi trabajo, que es manejar los cambios destructivos en un esquema GraphQL.

Entonces, solo una breve introducción sobre mí. Mi nombre es Kadi Kraman, actualmente soy la Directora de Desarrollo Móvil en Formidable. Si no has oído hablar de nosotros, Formidable es una consultoría. Construimos sitios web, aplicaciones móviles, y por supuesto, APIs GraphQL. En mis cinco años en esta empresa, creo que casi todos los proyectos tenían una API GraphQL en ellos. Así que hemos estado haciendo esto bastante. Allá por 2002, mi primera API GraphQL fue alrededor de 2017, y desde entonces, he trabajado con aplicaciones pequeñas y grandes, y principalmente como consumidor de API.

Entonces, porque construyo muchas aplicaciones móviles, generalmente he sido el cliente de una API GraphQL. Pasaría tal vez el 20 por ciento de mi tiempo escribiendo GraphQL, y el 80 por ciento de mi tiempo utilizando APIs GraphQL. Entonces, los cambios destructivos son algo que es muy relevante para mí porque soy el cliente que se ve afectado si ocurren cambios destructivos.

Entonces, ¿qué es un cambio destructivo? Un cambio destructivo en un esquema GraphQL es básicamente una actualización que hace que el contrato de la API cambie de una manera que no es compatible con versiones anteriores. Ahora, ¿qué significa esto realmente? Te lo voy a mostrar usando un ejemplo de código. Entonces, aquí tenemos un pequeño esquema. Tenemos una consulta donde puedes consultar un usuario por un ID y te devolverá un tipo de usuario. Y el tipo de usuario solo tiene el ID y el nombre en él. Ambos son campos obligatorios. Y si miramos cómo sería una consulta. Entonces, aquí a la derecha, vamos a consultar al usuario por ID, consultar el ID y el nombre, y obtenemos exactamente esos datos de vuelta. Entonces, supongamos que tenías este tipo de usuario en tu proyecto actual y el cliente regresa a ti y dice, oye, no queremos tener nuestro nombre como una sola cadena. Queremos tener el nombre y el apellido por separado. Entonces, como un nuevo requisito, necesitas separar el campo de nombre en nombre y apellido. Entonces, ¿cómo lo harías? Te sentirías tentado a hacer algo como esto. Entonces, aquí hemos agregado el nombre y el apellido que son ambas cadenas obligatorias. Pero entonces, porque realmente no usamos el nombre más, podemos eliminar el campo del nombre. Ahora, esto parece todo bien y bueno desde el lado del esquema, desde el lado de la API. Cuando miramos el lado del cliente y consultamos la misma consulta que hicimos antes, nos encontramos con un error. Y el error dice que no se puede consultar el campo nombre en el tipo de usuario. Y de hecho, el campo nombre ya no existe. Ahora, este es un ejemplo de un cambio destructivo.

Un cambio que no es compatible con versiones anteriores. Porque una consulta que funcionaba en la versión anterior de esta API ya no funciona debido a este cambio. Veamos cómo haríamos que este cambio sea compatible con versiones anteriores. Es sorprendentemente simple. En lugar de eliminar el campo, podemos agregar un aviso de obsolescencia utilizando la directiva deprecated. Aquí has visto junto al campo nombre, he agregado deprecated y también proporcioné una razón. Entonces, en este caso, está obsoleto a favor de nombre y apellido.

Y aquí podemos ver que la consulta anterior que solo consultaba el ID y el nombre todavía funciona y la nueva consulta que consulta el nombre y apellido también funciona. Por lo tanto, porque ambas consultas, la anterior y la nueva, funcionan, este es un cambio que es compatible con versiones anteriores. La directiva deprecated es realmente útil. Básicamente te permite etiquetar un campo en un esquema como un campo obsoleto para comunicar a tus consumidores que este campo ya no debería ser utilizado. Es parte de la especificación GraphQL, lo que significa que la mayoría de los servidores GraphQL deberían implementar. La parte más importante, la mayoría de los IDEs, herramientas GraphQL, y clientes que podrías estar utilizando recogerán esta notificación y te advertirán si estás utilizando un campo obsoleto.

Aquí he añadido un ejemplo. Esto es de Insomnia, que es un cliente GraphQL que utilizo para hacer consultas. Cuando miro el esquema y el tipo de usuario en particular, podemos ver que el nombre ahora tiene un signo de exclamación al lado. Si paso el cursor sobre él, me está diciendo que el campo nombre ahora está obsoleto, y también me está dando el mensaje de obsolescencia que escribí. Por lo tanto, está obsoleto a favor de nombre y apellido. Ahora puede haber una razón, sin embargo, raramente, que simplemente tendrías que introducir un cambio destructivo en la API. Así que voy a mostrarte una forma en que podrías introducir un cambio destructivo en una API GraphQL de manera relativamente segura. Las palabras clave que necesitas recordar son agregar, deprecar, migrar, eliminar. Desafortunadamente, no es un acrónimo muy bueno. Vamos a repasar estos uno por uno para mostrarte lo que significa cada paso. Así que este es nuestro estado inicial. Vamos a empezar con este tipo de usuario que usamos antes, solo con el id y un nombre. Y esta es nuestra pila de aplicaciones. Así que vamos a tener un sitio web, digamos que es una aplicación Xjs. Vamos a tener una API. Por supuesto, es una API GraphQL. Y porque construyo aplicaciones móviles, vamos a tener una aplicación React Native para iOS y Android en un tercer repositorio.

Así que estos tres están en repositorios separados y se despliegan por separado. Y la primera versión de estos web1, api1 y app1 implementan el tipo de usuario como se ve aquí.

Ahora, la primera etapa de agregar es bastante sencilla. Vamos a agregar los campos de esquema que necesitan ser agregados. En este caso, vamos a agregar el nombre y apellido al tipo de usuario.

La siguiente etapa de depreciar, normalmente la harías junto con agregar. Pero en este caso, vamos a depreciar cualquier campo que querríamos eliminar en el futuro. Aquí hemos añadido la directiva deprecated. Usamos la directiva deprecated para añadir un aviso de depreciación al campo nombre en el tipo de usuario.

Ahora, cuando hayamos terminado con todos nuestros cambios, lanzaremos una nueva versión de la API GraphQL a api2. Ahora, api2 sigue siendo compatible con app1 y web1, lo que significa que este es un cambio compatible con versiones anteriores.

El siguiente paso es la etapa de migración. Ahora, en este paso, tienes que revisar todos los clientes, todo lo que está usando tu API GraphQL, y actualizarlos para usar la nueva API. Luego iremos al sitio web y a la aplicación. Haremos el cambio y publicaremos las nuevas versiones y nos aseguraremos de que todos nuestros usuarios las estén utilizando.

Ahora, cuando estés seguro de que nadie está usando web1 y app1, y hayas publicado web2 y app2, entonces podría ser seguro eliminar el campo. Así que aquí podemos eliminar el campo nombre que fue depreciado del tipo de usuario y cuando hayamos terminado, desplegaremos la nueva versión de la API a api3. Ahora, api3 no es compatible con web1 y app1, todavía recibirían un error, pero si nadie los está usando, ya has publicado el cambio, estarán usando web2 y app2, entonces esa es una eliminación aceptable.

Ahora, como construyo aplicaciones móviles, no sería un desarrollador de aplicaciones móviles si en este punto no me desviara para explicar por qué esto es mucho más difícil en las aplicaciones móviles. A un nivel más alto, esto es lo que parece el despliegue de sitios web y APIs. Has terminado tu versión 1, la vas a subir a donde la lances, digamos AWS, estará disponible para los usuarios, y el 100% de tus usuarios la van a usar.

Ahora, cuando se trata de lanzar la v2, cuando termines de codificarla, la vas a subir a AWS, la vas a hacer disponible e instantáneamente todos tus usuarios van a cambiar y el 100% de tus usuarios estarán usando la v2 y nadie estará usando la v1. Cuando termines la v3, la lanzarás, el 100% de tus usuarios cambiarán inmediatamente.

Ahora, esto parece bastante obvio pero el hecho es que, esto no es en absoluto cómo funciona para las aplicaciones móviles. Esto es lo que parece el despliegue de una aplicación móvil. Cuando hayamos terminado nuestra v1, la vamos a subir a las tiendas, vamos a obtener una aprobación, y cuando tengamos la aprobación podemos publicarla en la app y play store. Y como es la primera versión de nuestra aplicación, el 100% de nuestros usuarios la van a usar.

Luego, cuando estemos listos para la v2, la vamos a lanzar a nuestras tiendas, vamos a obtener la aprobación, la vamos a lanzar a nuestras tiendas. Vamos a, en realidad toma tiempo así que vamos a irnos por dos semanas, vamos a mirar las estadísticas después de dos semanas, y veremos que quizás el 60% de los usuarios la usarán. Y el 40% de los usuarios todavía están usando la v1.

Y cuando hacemos otra versión, v3, la aprobamos, la lanzamos a las tiendas, nos vamos y volvemos después de dos semanas, encontraremos que quizás el 65% de los usuarios la están utilizando. El 30% de los usuarios todavía están en v2 y el 5% de los usuarios todavía están en v1. Ahora, la triste realidad es que los lanzamientos de mobile app nunca alcanzan el 100% de adopción como lo hacen los sitios web. Y la razón de eso es que las aplicaciones solo se actualizan si el usuario tiene activadas las actualizaciones automáticas o si van a la página de listado de la tienda y actualizan manualmente. Incluso si el usuario tiene activadas las actualizaciones automáticas, la actualización no sería instantánea, tan pronto como la aplicación esté disponible, se actualizará. En cambio, generalmente se actualizará una vez que conectes tu teléfono y lo conectes al Wi-Fi. Por lo tanto, podría haber un gran retraso entre el momento en que publicas la aplicación y los usuarios, incluso aquellos que están primeros en la fila, realmente la obtienen.

Sabiendo eso, podrías preguntarte, ¿cuándo es seguro hacer un cambio radical en la API, si es utilizada por una aplicación móvil? Bueno, la verdad que no quieres escuchar, es que en realidad nunca es seguro hacer tal cambio radical. Porque siempre afectarás a alguien, es imposible conseguir que el 100% de tus usuarios, una vez tu última versión.

Pero, ¿y si realmente, realmente, realmente tengo que hacerlo? Bueno, hay formas de hacer esta actualización lo más segura posible. Usualmente en las aplicaciones móviles, incorporamos, así que esto es algo que tendrías que incorporar como desarrollador, incorporaríamos un aviso de seguridad, que básicamente es un aviso que solicitaría a los usuarios que actualicen, si quieren seguir utilizando la aplicación. Generalmente, la mayoría de las aplicaciones lo tienen incorporado, pero es un último recurso, no queremos usar eso, nunca debería ser parte de tu flujo normal de desarrollo porque es una terrible experiencia de usuario y a los usuarios no les gusta, y para ser honesto, a Apple tampoco le gusta, y no queremos molestar a Apple.

Mientras trabajaba en esta masterclass, una de las aplicaciones que uso regularmente tenía este aviso de actualización de la aplicación, así que lo he añadido aquí como un ejemplo. Básicamente, cuando abro la aplicación, inmediatamente obtengo una alerta nativa que dice, esta versión está obsoleta, por favor ve a la tienda para actualizarla. Así que si presiono en aprender más, me llevará a la tienda de aplicaciones, donde me solicitará que actualice. De hecho, he visto que hicieron una revisión completa de toda la aplicación. Creo que la reescribieron, así que presumiblemente, la versión anterior ya no es compatible. Ahora, incluso cuando llegas a este punto, y has impedido a los usuarios usar la antigua versión de tu aplicación, técnicamente no puedes estar seguro de que van a actualizar. Porque en este punto, puedo elegir no presionar el botón de actualización en la tienda de aplicaciones porque tal vez no estoy en Wi-Fi y no quiero usar mis datos móviles. Y también puedo decidir que esto me molesta y voy a usar esta aplicación en el sitio web en su lugar, o no usarla en absoluto. Y una vez que has hecho todo lo posible para asegurarte de que los usuarios actualizarán, entonces tienes que monitorear que lo están haciendo. Harás esto en dos niveles. Uno es en el lado de la API y el otro es en el lado de la aplicación. Así que en el lado de la API, esto será tal vez en AWS o en CoreLogix. Puedes generar métricas para monitorear el uso de consultas. Así que puedes generar una métrica para monitorear el uso de campos obsoletos y verás si se llaman o no. Y luego, por otro lado, también puedes monitorear tus aplicaciones son usuarios activos para cada versión de la aplicación para tener una idea del número de usuarios que todavía están usando versiones de la aplicación que están obsoletas y que tienen este cambio radical y cuántos usuarios este cambio radical podría afectar. Y una cosa a tener en cuenta es que tener cambios radicales en la API generalmente es mucho más significativo para los usuarios y desarrolladores de aplicaciones móviles que para los usuarios y desarrolladores web. Porque en el sitio web, si tu sitio web se cae o no funciona, entonces usualmente tus usuarios podrían tuitearte, podrían tal vez enviar un correo electrónico a tu servicio al cliente enojados, mientras que si una aplicación está rota, si la API no funciona, entonces los usuarios tienen una forma muy agradable y conveniente de quejarse de ello y lo harán en la página de listado de la tienda y te darán una calificación de una estrella debido a un cambio de una sola línea donde tu API no funcionó. Alejándonos de ese tema sombrío, juguemos un pequeño juego. ¿Cuál de estos es un cambio radical? Así que tenemos el tipo de usuario con la ID y un nombre, y en un lado he hecho el nombre de obligatorio a opcional, y en el otro lado lo he hecho de opcional a obligatorio. ¿Viste el primero? En efecto, en un esquema GraphQL si tienes un campo que es obligatorio y luego lo cambias a opcional, eso es un cambio radical. ¿Y por qué es eso? Bueno, puede que no sea muy fácil verlo desde el esquema, pero será un poco más simple verlo como un ejemplo de código. Así que aquí está, he usado TypeScript sólo para hacerlo un poco más obvio. Y a la izquierda, tenemos algo de código que podrías tener en el front end que usa esta API. Así que porque nuestro usuario sólo tiene una id y un nombre, podría tener una función de utilidad que usa el nombre y toma las primeras partes de él como el primer nombre. Ahora después de haber hecho el cambio, así que hice el nombre de obligatorio a opcional.

Entonces podría devolver null. De hecho, TypeScript me está ayudando y me dice que no puedo llamar a split en el nombre del usuario porque podría ser null. Y de hecho, si en algún momento el nombre del usuario devuelve null, obtendría el error de JavaScript al llamar a esta función.

Hagamos uno más. En este caso, tengo la consulta de usuario y estoy cambiando el ID de usuario por el que estoy consultando de obligatorio a opcional o de opcional a obligatorio. ¿Viste el segundo? Sí, el segundo cambio es radical. Y puede ser confuso porque es lo contrario para las entradas de consulta porque aquí, cambiar el ID de usuario de opcional a obligatorio es radical, no al revés. He usado las diferencias aquí a propósito para que puedas ver que como revisor es realmente muy fácil pasar por alto este tipo de cambios.

Afortunadamente, hay una herramienta para ayudarte. Si aún no lo has hecho, definitivamente te recomendaría que eches un vistazo a GraphQL Inspector. Actualmente lo estamos utilizando en mi proyecto y ha marcado una gran diferencia. Hace un montón de cosas, pero lo más importante para nosotros es que nos permite tener una comprobación en las solicitudes de extracción, que nos dirá si se introducirá un cambio radical en la API. Puedes usar esto en cualquier tipo de CI. Usamos GitHub Actions, así que lo mostraré como ejemplo. Aquí lo que estamos configurando es que va a comparar el esquema GraphQL en el actual con el esquema GraphQL en tu rama de trabajo actual. Así es como se ve en la solicitud de extracción real. A la izquierda, vamos a ver un ejemplo de un cambio radical, así que lo tenemos configurado para fallar en CI, si hay un cambio radical. Y puedes ver que se están eliminando dos tipos. Eliminar tipos siempre es un cambio radical, y por lo tanto esto se resalta. Y lo otro interesante es que en realidad a la derecha, podemos ver algunos ejemplos de solo tipo de avisos de información. Así que estos no son errores o advertencias, es solo para información. Y lo que hace el GraphQL inspector es que resalta cualquier cambio, así que esto llamará la atención del revisor sobre lo que realmente ha cambiado. Y esto es realmente importante porque tienes que estar bastante consciente de lo que realmente estás añadiendo a tu API de GraphQL, porque como puedes ver en el otro lado, eliminar cualquier cosa siempre es un cambio radical. Así que una vez que lo añades, eliminarlo podría ser un FAF. Como hemos habilitado fallar en caso de ruptura, hay otra cosa que hemos añadido, que es tener una etiqueta aprobada. Así que puedes establecer tu propia etiqueta para un cambio radical aprobado, así que puedes llamarnos lo que quieras, pero este es nosotros. Así que básicamente, si añades esta etiqueta a una solicitud de extracción, entonces incluso si tenía un cambio radical, permitirá que el CI pase. Y esto es realmente útil porque básicamente, a medida que se introduce una solicitud de extracción, un revisor la revisará y se destacará que hay un cambio radical, y se necesita tener una conversación sobre si este es un cambio que estamos contentos de tener, si hay otra forma de hacerlo, y si debe evitarse por completo.

En resumen, hemos visto qué es un cambio radical en el esquema. Así que esto es renombrar un campo, eliminar un campo, cambiar el tipo de data, hacer un campo requerido opcional, o hacer una entrada opcional requerida. En general, debes evitar hacer cambios radicales tanto como sea posible, especialmente si tu API está siendo utilizada por una aplicación móvil, o cualquier tipo de aplicación de escritorio que no tenga el mismo tipo de flujo de publicación que los sitios web y las APIs. Pero si necesitas introducir un cambio radical, puedes usar el paso de añadir, depreciar, migrar, eliminar para minimizar la cantidad de usuarios que vas a afectar. Y finalmente, si aún no lo has hecho, te recomendaría mucho que eches un vistazo a GraphQL Inspector para mejorar tus flujos de trabajo de GraphQL API. Muchas gracias, espero que hayas aprendido algo sobre los cambios radicales en GraphQL.