El Secreto para la Incorporación de Gráficos

¡Hola a todos! Mi nombre es Danielle y soy directora de ingeniería en Apollo, donde he estado trabajando en ayudar a las personas a utilizar gráficos durante más de cinco años. Y hoy quiero compartir algunos consejos contigo sobre cómo configurar tu gráfico para que otras personas puedan usarlo con éxito.

Esta charla será un poco diferente a una inmersión profunda en GraphQL estándar porque en lugar de hablar sobre algunos de los elementos que intervienen en la construcción de un gráfico, me gustaría hablar sobre cómo las personas utilizan los gráficos. Y en particular, me gustaría hablar sobre cómo hacer que tu gráfico sea más utilizable para otras personas.

Tal vez te preguntes, ¿por qué es importante tomar medidas explícitas para hacer que tu gráfico sea más utilizable? Bueno, GraphQL tiene la introspección incorporada en su especificación, por lo que es autoexplicativo, ¿verdad? Y el ecosistema de GraphQL tiene muchas herramientas maravillosas que se generan automáticamente a partir de la introspección de GraphQL para crear cosas como diagramas de esquema y sitios de documentación rápidos. Pero la realidad es que, al igual que cualquier otro código que escribas o cualquier otro producto que tenga un poco de éxito, eventualmente crecerá y crecerá. Y necesitarás escalar la velocidad de desarrollo de tus gráficos más allá de una sola persona o un solo equipo de personas. Y cuanto más pienses en cómo quieres usar tu gráfico desde el principio, más fácil será incorporar a nuevas personas a tu gráfico en el futuro.

Así que hoy, hablaré primero sobre cómo las personas que están ejecutando gráficos a gran escala están incorporando a los desarrolladores en sus gráficos tanto para consumir como para contribuir. Y luego, la mayor parte de nuestro tiempo, escribiré código junto con ustedes y les mostraré cómo pueden configurar su gráfico con una experiencia similar a un portal para desarrolladores para que otras personas puedan conectarse con muy poco esfuerzo. Así que vamos a sumergirnos.

Siento que la comunidad de GraphQL está inundada de contenido técnico relacionado con cómo escalar un gráfico. Pero no he visto mucho contenido sobre el lado humano de escalar un gráfico. Así que pregunté a algunos de nuestros clientes y a algunas personas de nuestra comunidad, ¿qué hacen para incorporar a nuevas personas a su gráfico? Y recibí muchas respuestas con superposición. Así que fue emocionante ver muchos de los patrones y lo que la gente estaba haciendo.

Muchas personas están utilizando canales internos de Slack con el hashtag GraphQL para estar disponibles para preguntas y crear procesos en torno a cosas como el diseño de esquemas. Muchas personas organizan sesiones regulares de incorporación para ayudar a los nuevos equipos a comenzar. Las personas también organizan sesiones mensuales de almuerzo y aprendizaje y charlas informales sobre temas avanzados de GraphQL o para hablar sobre cosas nuevas que están sucediendo en el ecosistema. Y muchas personas han creado una sección de gráficos en sus wikis internos. Algunas personas incluso han creado sitios web completos de gráficos. Y estos sitios les indican a las personas cómo comenzar con un gráfico, cómo autenticarse con las necesidades únicas de cada empresa, qué tipos de convenciones sigue este gráfico, etc.

Algunas de mis respuestas favoritas que recibí fueron en realidad sobre las herramientas que las personas han configurado para hacer cumplir que su gráfico se utilice de acuerdo con las reglas de la empresa. Un ejemplo es que hay muchas formas en que las personas configuran la observabilidad para sus APIs. Y con GraphQL, una vez que agregas algo a un gráfico, se vuelve descubrible a través de la introspección. Por lo tanto, es muy posible que agregues un campo a tu esquema para tu propio uso, pero alguien más en otro departamento también podría comenzar a usarlo. Entonces, si requieres que cada solicitud que se realice a tu gráfico tenga encabezados para identificar qué cliente está realizando esas solicitudes, entonces puedes configurar la observabilidad para recibir alertas cada vez que un nuevo cliente comienza a usar tu campo, lo cual se convierte en información realmente útil a medida que evolucionas un gráfico. Y lo que tengo en esta diapositiva es solo un ejemplo de cómo se ve la observabilidad a nivel de cliente en Apollo Studio.

Otro patrón que me gustó mucho fue la idea de establecer algunas convenciones de nomenclatura para tus operaciones. Entonces, en primer lugar, una cosa que puedes hacer es asegurarte de que cada operación en tu servidor tenga un nombre, pero además de eso, puedes establecer convenciones de nomenclatura para que todas tus operaciones tengan un nombre estandarizado. Y esto se vuelve realmente útil a largo plazo porque inevitablemente, un día, tendrás algún problema con alguna sección de tu gráfico, y si todas tus operaciones siguen una convención de nomenclatura estándar, será muy fácil determinar qué partes de tus productos se ven afectadas por este problema del gráfico. Entonces, aunque los nombres de las operaciones no son identificadores únicos, en la práctica son realmente útiles como herramienta para la resiliencia del producto.

Y luego, en cuanto a las herramientas para desarrolladores, hubo un patrón de personas que configuraban herramientas de linting de esquema y consultas que me gustó mucho. Un ejemplo de esto es en un gráfico federado donde tienes muchos subgráficos que son propiedad y están controlados de forma independiente por diferentes equipos, a menudo puede ser realmente útil hacer cumplir que cada esquema de subgráfico tenga información de contacto en el propio esquema. Y puedes usar directivas de GraphQL para definir información de contacto. Y luego puedes usar herramientas de linting de esquema y GraphQL para asegurarte de que esas directivas estén presentes. Y una de las cosas interesantes de usar el esquema y las directivas y el linting para capturar todos esos metadatos es que todas las herramientas más adelante en el ecosistema de GraphQL pueden hacer uso de esos metadatos también. Aquí en la captura de pantalla tengo una imagen de la página de documentación como la documentación de esquema para un gráfico en Studio que muestra información de contacto sobre el subgráfico al que pertenece un campo en particular. Y hay muchas más convenciones que podrías establecer en esta misma línea.

¿Cómo quieres que tu gráfico maneje el lanzamiento de errores es un tema muy importante en GraphQL. ¿Cómo quieres que tu gráfico maneje la autenticación? ¿Hay un patrón que quieras seguir para los tipos de argumentos que las mutaciones van a tomar en el esquema? ¿Hay una nomenclatura particular que quieras asegurarte de que las personas cumplan al agregar cosas nuevas al esquema? Y en medio de todo este proceso de incorporación y enseñar a las personas cómo usar el gráfico y establecer convenciones para ellos, también debes tener en cuenta que muchas personas vendrán a tu gráfico sin mucha experiencia en GraphQL en absoluto. Por lo tanto, necesitas tener una forma de brindarles esta información que necesitan para tener éxito sin abrumarlos por completo o hacer que la barrera de entrada a tu gráfico sea demasiado alta.

Y a través de todos estos comentarios que recibí de estos equipos sobre cómo incorporan a los desarrolladores en su gráfico, lo que fue consistente para casi todos los equipos es que habían creado algún tipo de portal para desarrolladores. Y estos portales tenían diferentes formas, sitios web, wikis, incluso documentos de Google. Pero cada equipo tenía alguno, cada equipo necesitaba crear algún tipo de centro para todo este contenido.

Y puede parecer que construir un portal completo para desarrolladores es una tarea grande y, por lo tanto, algo que debes hacer solo cuando estés listo para comenzar a escalar tu gráfico fuera del contexto del equipo que inició el gráfico. Pero hay cosas nuevas en el ecosistema de Apollo que hacen que compartir tu gráfico sea mucho más fácil de lo que solía ser. Y quiero mostrarte lo fácil que puede ser esto.

Entonces, con la mayoría de nuestro tiempo restante, quiero escribir código juntos y pasar por el proceso de configurar un portal para desarrolladores completamente personalizado para el gráfico solo para mostrarte lo accesible que es ahora. Así que tengo una pequeña demostración aquí para que comencemos. Y deberías poder acceder a este código sandbox escaneando ese código QR. Y este es en realidad un gráfico que creé hace aproximadamente un año y medio, cuando COVID golpeó por primera vez y pasé a trabajar desde casa. Porque en mi rutina de trabajo desde casa, comencé a intentar establecer algunas rutinas y creé este hábito de salir a caminar y comprar un bagel todas las mañanas antes del trabajo para ponerme en el estado mental correcto.

Y un par de meses después, comencé a preguntarme, ¿cuánto me está costando este hábito de caminar con bagel en mi presupuesto? Y siendo el desarrollador de GraphQL que soy, pensé que la mejor manera de responder a esa pregunta es obviamente hacer un gráfico para consultar esos datos. Así que aquí tengo un gráfico que puede consultar información de transacciones financieras. Es un gráfico muy, muy ligero. Es un servidor de Apollo sin configuración en este momento, es solo un servidor de Apollo muy simple 3. Y en mi esquema, mi esquema es muy pequeño, solo tengo un campo en el tipo de consulta raíz, que son las transacciones que podemos consultar. Y en mis resolutores aquí.

La forma en que funciona este gráfico en el fondo es que estamos utilizando la API de transacciones financieras de Plaid. Entonces, Plaid es una empresa que proporciona una API de transacciones financieras como servicio, y ellos tienen una API REST. Y esta API de GraphQL es realmente solo un envoltorio muy ligero alrededor de su API REST. Y estamos utilizando el cliente de nodo de Plaid con sus enlaces de API de Plaid para traducir nuestro resolutor de transacciones en una llamada a su API. Y luego aquí en las mutaciones, tengo dos pequeñas mutaciones para obtener un token de enlace y obtener un token de acceso. Y estas mutaciones son cómo facilitamos la autenticación con este gráfico. Entonces aquí puedo venir aquí y puedo consultar este servidor y abriremos el sandbox de Apollo y puedo pedir transacciones y tal vez su monto y su nombre aquí. Pero si ejecuto esta solicitud, voy a obtener un error que dice que no estás autenticado porque no hay nada que podamos hacer de manera significativa con este gráfico sin autenticar porque se trata de transacciones financieras.

Y si queremos invitar a los desarrolladores a participar en la contribución a este gráfico, queremos brindarles una experiencia donde puedan venir y hacer cualquier consulta que deseen a voluntad, pero queremos facilitarles el inicio de sesión porque no queremos que tengan que venir aquí, obtener un token de enlace, ir a algún otro sitio web, intercambiarlo por un token de autenticación, volver y ponerlo en las cabeceras, eso es mucho trabajo. Sería mucho mejor si pudieran tener un sitio web que visitar que se sienta casi completamente como esto, pero también tenga un botón de inicio de sesión que puedan presionar y autenticarse directamente en el lugar. Entonces, para hacer eso, vamos a necesitar crear una página web personalizada. No podemos simplemente usar el sandbox tal cual, y creo que el mejor lugar para nuestra página web es en realidad ponerla en la misma URL que nuestro servidor porque entonces será bastante fácil de encontrar. Entonces, lo que vamos a querer hacer es cambiar la página de inicio predeterminada de Apollo Server y poner nuestra página personalizada allí.

Y podemos hacer eso conectándonos a la arquitectura de complementos de Apollo Server. Aquí, Apollo Server define una variedad de complementos. Bueno, hay todo un ecosistema de complementos, pero Apollo Server tiene una API de complementos que te permite definir tus propios complementos. Y podemos volver a nuestro servidor, agregar este complemento que coloca el HTML y la cadena en la página de inicio en lugar de la página de inicio predeterminada, y ahora puedes ver que nuestro servidor está sirviendo ese HTML.

Y lo que queremos es tener esa experiencia del botón de inicio de sesión, así que he preparado un poco de HTML de antemano, para que no tengamos que escribirlo en el momento. Y en mi archivo HTML que tenemos aquí, tengo algunas funciones auxiliares en la parte superior de nuestro archivo. La única estructura real del DOM de este archivo es el botón que tenemos para iniciar sesión y luego un pequeño span para mostrar el contexto de inicio de sesión. Y luego aquí abajo, tengo un controlador de clic para facilitar la autenticación. Entonces, cuando se hace clic en este botón, obtenemos un token de enlace de esa mutación en nuestra API. Abrimos el controlador de inicio de sesión de Plaid. Y si tienes un inicio de sesión exitoso con este controlador de inicio de sesión, por favor, no compartas mi contraseña bancaria, por favor. Esta es información muy, muy confidencial. Si tenemos un inicio de sesión exitoso con este controlador de inicio de sesión, entonces, cuando tengamos éxito con esos datos que recibimos de nuestra mutación, colocaremos ese token de autenticación en el almacenamiento local. Así que ahora nuestro pequeño sitio web aquí tiene un token de Plaid en su almacenamiento local.

Y lo que queremos hacer es combinar este sitio web y este botón de inicio de sesión con una experiencia de IDE de consultas. Y la forma en que vamos a hacer eso es utilizando una nueva función de Apollo Server llamada gráficos públicos. Entonces, puedes crear un nuevo gráfico en Apollo Studio basado en un esquema de cualquier lugar. En nuestro caso, lo haremos basado en un esquema de introspección de nuestro código sandbox. Y si hacemos que este gráfico sea público, entonces en nuestra página de Explorer, hay una configuración que se vuelve disponible para nosotros, que es una configuración para incrustar este Explorer en otros sitios web. Y aquí tenemos algunas opciones. Queremos incrustar un Explorer oscuro porque lo estamos colocando en el código sandbox. Probablemente queremos ocultar nuestro panel de documentación porque el código sandbox es bastante pequeño. Y luego vamos a ocultar los encabezados y las variables de entorno porque queremos manejar la autenticación a través de nuestro sitio web para que los usuarios no tengan que pensar en cómo manejar la autenticación en los encabezados. Así que vamos a copiar este código ahora, volver a nuestro código sandbox y en nuestro archivo HTML, justo debajo de nuestros botones, pegaremos eso. Reiniciaremos nuestro sandbox, actualizaremos nuestra página y ahora tenemos un Explorer incrustado.

Pero este Explorer incrustado sigue siendo solo un iframe que realiza solicitudes a nuestro servidor desde un iframe en otro sitio web. Así que aún no hemos resuelto completamente nuestro problema porque lo que realmente queremos hacer es que nuestro sitio web principal realice solicitudes en nombre del Explorer y no que el Explorer realice una solicitud desde el iframe. Entonces, vamos a entrar en la configuración avanzada de Explorer y vamos a definir esta función de manejo de solicitudes dentro de la configuración de Explorer. Y nuestra función de manejo de solicitudes aquí, básicamente queremos que la solicitud se envíe tal como lo haría el Explorer, pero queremos agregar este encabezado, que es el token que vamos a sacar de nuestro almacenamiento local, este encabezado de autenticación.

Entonces, ahora si guardo esto, reinicio mi sandbox, actualizo mi página HTML y hago esta solicitud, ahora deberíamos tener solicitudes autenticadas. Y si cambiamos la consulta predeterminada de nuestra página para que sea un poco más interesante, como por ejemplo, podríamos consultar en lugar del propietario de la cuenta, que es solo el campo predeterminado que obtuvimos, el monto y el nombre, entonces cuando actualicemos esto y ejecutemos la consulta, obtendremos nuestras transacciones de vuelta.

Y ahora cualquier desarrollador que visite nuestro pequeño portal de desarrolladores en el futuro podrá iniciar sesión en su cuenta bancaria y obtener de inmediato sus transacciones con solo un clic de inicio de sesión y un clic para ejecutar la consulta. Ahora que nuestro gráfico es muy fácil de consultar, su popularidad va a despegar por completo. Lo sé, porque todos querrán saber cuánto les cuestan sus bagels. Y antes de que eso suceda, creo que deberíamos implementar algunas protecciones para que las personas sigan las reglas de uso de nuestro gráfico desde el primer día.

Y una de las reglas que teníamos en nuestras diapositivas era que queremos que cada solicitud que llegue a nuestro gráfico tenga los encabezados requeridos. Entonces, en este caso, digamos que queremos que cada solicitud tenga un encabezado de nombre de cliente de Apollo GraphQL requerido, porque luego podemos conectarlo a nuestra otra observabilidad. La forma en que vamos a lograr esto es ampliando la lógica en esta función de contexto. Entonces, si una solicitud no tiene nuestro encabezado de nombre de cliente de Apollo GraphQL, vamos a lanzar un nuevo error, todas las solicitudes deben provenir de un cliente identificado. Ahora, si ejecuto esta consulta, deberíamos obtener ese error de vuelta, lo cual estamos obteniendo, porque nuestra pequeña página web aquí aún no se está identificando como un cliente. Pero aquí, al igual que ampliamos nuestra solicitud usando esta función de manejo de solicitudes con un encabezado de autorización, también podemos agregar fácilmente un encabezado de nombre de cliente de Apollo GraphQL, y simplemente decir que este es nuestro explorador incrustado del portal. Ahora, si actualizo mi página aquí y ejecuto esta consulta, deberíamos estar listos para continuar. Y si echamos un vistazo a nuestras herramientas de observabilidad, ahora las solicitudes que provienen de nuestro explorador incrustado del portal se identificarán como tal.

Entonces, ahora que estamos haciendo cumplir que los encabezados requeridos estén presentes en nuestras solicitudes, otra regla que teníamos en las diapositivas era que todas las operaciones también deben tener un nombre adjunto. Esto es un poco más complicado porque a diferencia de los encabezados, que son solo una propiedad que se puede extraer directamente de la solicitud, los nombres de las operaciones están incrustados en el cuerpo de la operación y el cuerpo de la operación, cuando se envía a través de la red y llega por primera vez a nuestro servidor, está completamente en un formato de cadena. Y para saber si la operación realmente tiene un nombre, tenemos que hacer que nuestro servidor analice esa operación en un árbol de sintaxis abstracta y luego preguntar en ese punto, ¿tiene esta operación un nombre? Desafortunadamente, no podemos simplemente seguir ampliando la lógica que tenemos en el contexto aquí, pero afortunadamente podemos aprovechar la arquitectura de complementos de Apollo Server 3. Entonces, aquí abajo, si volvemos a la documentación del servidor Apollo, y vemos cómo funciona el ciclo de vida del complemento de solicitud, hay un conjunto completo de estados por los que pasa cada solicitud en el servidor Apollo, y en cualquier momento podríamos conectar a los estados y agregar algo de lógica mejorada. Y así, la primera etapa del ciclo de vida de la solicitud, donde la operación de solicitud se ha analizado completamente, es la etapa justo después de que la validación haya comenzado, por lo que esto sería resolvió la operación. Entonces, vamos a entrar aquí y conectarnos, vamos a agregar otro complemento, y luego conectarnos a la operación resuelta y su contexto. Y todo esto está dentro del ciclo de vida de la solicitud que comenzó. Entonces, aquí vamos a decir que si no hay un context.operation name, lanzamos un nuevo error, todas las operaciones deben tener un nombre. Y ahora, si ejecuto nuestra operación nuevamente, deberíamos estar bien porque esta operación tiene un nombre, pero si elimino ese nombre y ejecuto esta operación, deberíamos obtener un error. Así que estamos listos para continuar. Con solo un pequeño complemento en Apollo Server y algo de lógica en nuestra función de contexto, ahora estamos haciendo cumplir automáticamente que todos los clientes que usan nuestro gráfico sigan nuestras reglas. Y a medida que este gráfico despegue y más personas descubran que pueden usar nuestra API y aprender todo sobre sus transacciones de bagels, ahora sabremos exactamente quién está usando nuestra API y cómo, lo cual es bastante asombroso. Y lo último que quería cubrir en nuestra demostración es cómo hacer que este gráfico sea realmente accesible. Es una cosa darles a las personas que van a desarrollar en contra de nuestro gráfico un enlace a este sandbox que creamos y decirles, adelante, descúbrelo, buena suerte. Pero es otra cosa completamente diferente darle a alguien un enlace a una página de inicio que los reciba y les diga por dónde empezar. Y les mostré cómo hacer un gráfico público en el estudio anteriormente porque así es como incrustamos el explorador, pero no expliqué realmente