¿Cómo se ejecuta una consulta de introspección de Sui GraphQL?

Sui expone una interfaz GraphQL que se sitúa junto a sus API gRPC y JSON-RPC. GraphQL te ofrece un esquema tipado, por lo que en lugar de memorizar nombres de métodos puedes preguntar al endpoint qué admite. Eso es exactamente lo que hace una consulta de introspección: devuelve el propio esquema, incluidos tipos, campos, argumentos y descripciones.

Este tutorial explica cómo enviar una consulta de introspección a un endpoint de Sui GraphQL, leer la respuesta y convertir ese esquema en consultas funcionales. También aborda la pregunta práctica que los desarrolladores se hacen a continuación: ¿deberías dirigir la introspección y el tráfico de la aplicación a un endpoint compartido, o pasar a infraestructura dedicada?

Cuándo la introspección es la opción correcta (y cuándo no)

La introspección es una función de desarrollo y herramientas, no una ruta de datos de producción. Úsala cuando estés explorando el esquema, generando clientes tipados o validando que un campo sigue existiendo después de una actualización de la red.

Si aún estás decidiendo entre las interfaces de Sui, la descripción general de la API de Sui es un buen punto de partida antes de comprometerte con GraphQL.

Conceptos básicos del endpoint de Sui GraphQL

Un endpoint de Sui GraphQL acepta solicitudes HTTP POST con un cuerpo JSON que contiene una cadena query y variables opcionales. El endpoint es una única URL; seleccionas la forma de los datos a través de la propia consulta en lugar de mediante rutas diferentes.

Antes de enviar una consulta de introspección, confirma tres cosas:

1. La URL del endpoint al que te diriges (mainnet o testnet).
2. Que el endpoint acepta cuerpos POST application/json.
3. Si el endpoint restringe la introspección en producción.

Algunos proveedores gestionados desactivan la introspección en endpoints compartidos para reducir la carga, mientras que los nodos dedicados normalmente la dejan habilitada. Si la introspección devuelve un error sobre estar deshabilitada, eso es una elección de configuración, no un error en tu consulta.

Enviar tu primera consulta de introspección

La consulta de introspección estándar es verbosa porque recorre todo el sistema de tipos. Comienza con una consulta más pequeña que liste los campos de la consulta raíz, luego amplíala una vez que confirmes que el endpoint responde.

curl -s https://your-sui-graphql-endpoint.example/graphql \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "{ __schema { queryType { name } types { name kind } } }"
  }'

Reemplaza la URL de marcador de posición con el endpoint GraphQL de tu proveedor. La respuesta contiene un objeto data.__schema. queryType.name te indica el nombre del tipo de consulta raíz, y types lista cada tipo en el esquema con su kind (OBJECT, SCALAR, ENUM, INPUT_OBJECT, etc.).

Si obtienes un objeto data de vuelta, el endpoint está funcionando. Si obtienes un array errors, lee el mensaje con atención; normalmente te dice si el problema es autenticación, una función deshabilitada o una consulta mal formada.

Leer la respuesta del esquema

El resultado completo de la introspección es grande. En lugar de volcarlo a la terminal, redirígelo a un archivo y consúltalo localmente.

curl -s https://your-sui-graphql-endpoint.example/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  > sui-schema.json

Ahora puedes inspeccionarlo con jq:

jq '.data.__schema.types[] | select(.name == "Query") | .fields[].name' sui-schema.json

Ese comando lista los campos de nivel superior disponibles en el tipo de consulta raíz. Desde ahí puedes profundizar en cualquier tipo para ver sus campos y argumentos. Esta es la forma más rápida de responder preguntas como "cuál es el nombre exacto del campo para un digest de transacción" sin leer documentación externa.

Convertir el esquema en una consulta funcional

Una vez que conoces los nombres de los campos, construye una consulta pequeña y pruébala. Un patrón típico es obtener un solo objeto por un identificador y seleccionar solo los campos que necesitas.

const query = `
  query GetObject($id: SuiAddress!) {
    object(address: $id) {
      address
      version
      digest
    }
  }
`;

const res = await fetch("https://your-sui-graphql-endpoint.example/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query, variables: { id: "0x..." } })
});

const json = await res.json();
console.log(json.data);

Los nombres exactos de los campos y los tipos de argumentos provienen de tu resultado de introspección, así que trata el fragmento anterior como una forma y no como una garantía de copiar y pegar. Si un nombre de campo difiere en tu endpoint, el esquema es la fuente de verdad.

Introspección en CI: detectar la deriva del esquema

El esquema de Sui evoluciona. Los campos se añaden, se deprecan o se renombran. Si tu aplicación depende de un campo que desaparece, lo descubrirás en producción a menos que lo verifiques antes.

Un patrón práctico es almacenar una instantánea del resultado de la introspección y compararla en cada despliegue:

# Guarda una línea base una vez
curl -s $SUI_GRAPHQL_ENDPOINT -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  > schema-baseline.json

# En CI, obtén el esquema actual y haz diff
curl -s $SUI_GRAPHQL_ENDPOINT -H 'Content-Type: application/json' \
  -d '{"query":"{ __schema { types { name kind fields { name } } } }"}' \
  > schema-current.json

diff <(jq -S . schema-baseline.json) <(jq -S . schema-current.json)

Un diff no vacío no es automáticamente un fallo, pero es una señal para revisar si tus consultas aún coinciden con el esquema. Esto es especialmente útil antes de una actualización de la red.

Errores comunes de introspección y qué significan

Si encuentras repetidamente tiempos de espera agotados en la consulta de introspección completa, solicita solo los tipos que te interesan. La introspección admite filtrado recorriendo tipos específicos en lugar de todo el esquema.

Elegir un endpoint para introspección y tráfico de la aplicación

La introspección es barata de ejecutar ocasionalmente pero costosa si la machacas. El endpoint que usas para explorar el esquema no tiene que ser el mismo que tu aplicación usa para lecturas de producción.

Una división común se ve así:

• Desarrollo y CI: un endpoint gestionado que permite introspección, usado para generación de código y diffs de esquema.
• Lecturas de producción: un nodo dedicado con consultas fijas, capacidad predecible y sin sobrecarga de introspección.

OnFinality proporciona tanto acceso a la API RPC como infraestructura de nodos dedicados para Sui. Si quieres entender cómo sopesar endpoints compartidos versus dedicados, la guía sobre elegir un proveedor de RPC cubre las ventajas y desventajas, y precios de RPC muestra cómo se estructuran los planes. También puedes revisar las redes RPC compatibles para ver dónde encaja Sui en la oferta más amplia.

Puntos clave

• Una consulta de introspección de Sui GraphQL devuelve el esquema, lo que te permite descubrir tipos y campos en tiempo de ejecución.
• Comienza con una consulta de introspección estrecha, luego amplíala una vez que el endpoint responda.
• Redirige las respuestas grandes a un archivo e inspecciónalas con jq en lugar de leer JSON sin procesar.
• Algunos endpoints compartidos desactivan la introspección; los nodos dedicados normalmente la permiten.
• Almacena una instantánea del esquema y haz diff en CI para detectar la deriva del esquema antes de que rompa producción.
• Separa tu endpoint de exploración de esquema de tu ruta de lectura de producción.

Preguntas frecuentes

¿Sui GraphQL admite la consulta de introspección estándar? Sí, la interfaz GraphQL de Sui sigue la especificación GraphQL, por lo que los campos de introspección __schema y __type funcionan donde el endpoint permite la introspección.

¿Por qué la introspección devuelve un error en mi endpoint? La razón más común es que el proveedor desactiva la introspección en endpoints compartidos para reducir la carga. Consulta la documentación de tu proveedor o cambia a un nodo dedicado.

¿Puedo usar la introspección para generar un cliente tipado? Sí. Guarda el resultado de la introspección y aliméntalo a un generador de código GraphQL para producir consultas tipadas para tu lenguaje.

¿Es seguro ejecutar la introspección en producción? Es seguro ejecutarla ocasionalmente, pero no es una ruta de datos. Mantenla en desarrollo y CI, y usa consultas fijas para el tráfico de producción.

¿Con qué frecuencia cambia el esquema de Sui GraphQL? El esquema evoluciona con las actualizaciones de la red. Hacer diff de una instantánea almacenada en CI es la forma más sencilla de estar al tanto de los cambios.

¿Necesito un nodo dedicado para usar GraphQL? No, pero un nodo dedicado te da acceso consistente y evita restricciones de endpoints compartidos como la introspección deshabilitada. Consulta Sui RPC para opciones de endpoint.