Superficies de acceso a datos de Sui: JSON-RPC, gRPC y GraphQL comparados

Las tres superficies de acceso a datos de Sui de un vistazo

Sui expone actualmente tres superficies principales de acceso a datos, cada una con un centro de diseño diferente. JSON-RPC es la superficie heredada orientada a métodos: llamas a métodos con nombre como sui_getObject o sui_executeTransactionBlock y recibes respuestas JSON. gRPC es la superficie tipada más nueva, HTTP/2 + Protobuf, utilizada por el SDK actual; define servicios y mensajes en archivos .proto y genera código de cliente. GraphQL es una superficie de consulta respaldada por indexador con vista relacional y paginación por cursor, que permite a los clientes solicitar exactamente los campos que necesitan en una sola ida y vuelta.

No son marcas competidoras de lo mismo. Difieren en tipado, frescura, flexibilidad y herramientas. JSON-RPC es universal y no requiere esquema, pero es más verboso y está siendo desenfatizado con el tiempo. gRPC es eficiente y capaz de streaming pero necesita generación de código y HTTP/2. GraphQL es flexible y expresivo pero está respaldado por indexador, por lo que puede retrasarse respecto a la punta de la cadena. Las referencias de la API de Sui documentan estas superficies como rutas de acceso distintas, y la introducción a gRPC explica el modelo RPC tipado HTTP/2 que sustenta la superficie gRPC.

Elegir una superficie es una decisión sobre compensaciones, no una cuestión de que una sea universalmente mejor. Para una orientación más amplia sobre redes Sui, consulta la página de red Sui y el centro de aprendizaje de OnFinality.

• JSON-RPC: orientado a métodos, universal, sin esquema, más verboso, siendo desenfatizado.
• gRPC: tipado HTTP/2 + Protobuf, eficiente, streaming, requiere generación de código.
• GraphQL: forma especificada por el cliente, lecturas anidadas en una sola ida y vuelta, respaldado por indexador por lo que puede retrasarse respecto a la punta.

JSON-RPC: la superficie heredada orientada a métodos

JSON-RPC en Sui sigue la especificación JSON-RPC 2.0: envías un objeto de solicitud con jsonrpc, method, params e id, y recibes una respuesta con result o error. La superficie está orientada a métodos—cada operación es un método con nombre como sui_getObject, sui_getTransactionBlock o sui_getLatestCheckpointSequenceNumber. Como no tiene esquema a nivel de transporte, puedes llamarlo desde cualquier cliente HTTP sin generación de código.

La compensación es la verbosidad. Obtener un objeto con campos anidados puede requerir múltiples llamadas: una para el objeto, otra para sus campos dinámicos, otra para la transacción que lo creó. No hay forma de especificar una forma de respuesta; obtienes la estructura JSON fija del método. JSON-RPC también está siendo desenfatizado con el tiempo, por lo que el trabajo nuevo debería preferir gRPC o GraphQL cuando estén disponibles. Para un recorrido práctico de la superficie JSON-RPC, consulta la guía RPC de Sui (RPC Assistant).

El soporte del proveedor para JSON-RPC está documentado pero varía según el proveedor y la versión de la red. Algunos proveedores exponen el conjunto completo de métodos; otros pueden restringir o deprecar métodos específicos. Siempre verifica la documentación de tu proveedor para la lista actual de métodos.

• Universal: funciona desde cualquier cliente HTTP, sin generación de código.
• Verboso: las lecturas anidadas pueden requerir múltiples idas y vueltas.
• Forma de respuesta fija: sin selección de campos especificada por el cliente.
• Desenfatizado: el trabajo nuevo debería preferir gRPC o GraphQL.

gRPC: la superficie tipada HTTP/2 + Protobuf

gRPC es la superficie tipada más nueva utilizada por el SDK actual de Sui. Utiliza HTTP/2 para el transporte y Protobuf para la serialización de mensajes, con servicios y mensajes definidos en archivos .proto. La introducción a gRPC describe el modelo: un cliente llama a un método en un servicio, y el cliente generado maneja la serialización, el framing y la gestión de conexiones. Esto te brinda verificación de tipos en tiempo de compilación y cargas binarias eficientes.

gRPC admite streaming, lo cual es útil para servicios de ledger y checkpoints. También tiende a ser más eficiente que JSON-RPC para lecturas de alto volumen porque las cargas Protobuf son más pequeñas y HTTP/2 permite multiplexación. El costo es la herramienta: necesitas generar código de cliente a partir de los archivos .proto, y tu entorno de ejecución debe admitir HTTP/2. Para una inmersión más profunda, consulta la guía de la API gRPC de Sui.

Al igual que JSON-RPC, la disponibilidad de gRPC está documentada pero varía según el proveedor y la versión de la red. Algunos proveedores exponen el conjunto completo de servicios; otros pueden exponer un subconjunto. Verifica la documentación de tu proveedor para la lista actual de servicios y métodos.

• Tipado: verificación en tiempo de compilación mediante clientes generados.
• Eficiente: cargas binarias Protobuf y multiplexación HTTP/2.
• Streaming: admite streaming del lado del servidor para datos de ledger y checkpoints.
• Costo de herramientas: requiere generación de código y soporte HTTP/2.

GraphQL: la superficie de consulta respaldada por indexador

GraphQL es una superficie de consulta respaldada por indexador con vista relacional y paginación por cursor. A diferencia de JSON-RPC y gRPC, GraphQL permite al cliente especificar la forma de la respuesta: escribes una consulta que nombra exactamente los campos que deseas, y el servidor devuelve solo esos campos. Esto es especialmente útil para lecturas anidadas—obtener un objeto junto con sus campos dinámicos, propietario y transacciones recientes en una sola ida y vuelta. La página de aprendizaje de GraphQL explica el modelo de consulta de punto final único, el esquema y la introspección.

La advertencia clave es la frescura. Dado que GraphQL está respaldado por indexador, puede retrasarse respecto a la punta de la cadena. El indexador ingiere checkpoints y construye una vista relacional; hay un retraso entre que una transacción se finaliza en la cadena y aparece en el índice. Esto significa que la misma consulta lógica puede devolver datos en una posición de cadena ligeramente diferente a una lectura directa del nodo. Para una inmersión más profunda, consulta la superficie de consulta de la API GraphQL de Sui.

GraphQL es muy adecuado para agregación histórica, lecturas anidadas y formas especificadas por el cliente. Es menos adecuado para flujos críticos para la consistencia que deben leer en la punta exacta. El soporte del proveedor para GraphQL está documentado pero varía según el proveedor y la versión de la red.

• Forma especificada por el cliente: solicita exactamente los campos que necesitas.
• Lecturas anidadas: obtén datos relacionados en una sola ida y vuelta.
• Respaldado por indexador: puede retrasarse respecto a la punta de la cadena.
• Paginación por cursor: eficiente para conjuntos de resultados grandes.

Tabla de decisión: asignación de tareas comunes a superficies

La siguiente tabla asigna tareas comunes de datos de Sui a la superficie que mejor se ajusta a ellas. Este es un punto de partida, no una regla rígida; las superficies admitidas por tu proveedor y tus requisitos de consistencia pueden cambiar la elección.

Para enviar o inspeccionar una transacción, gRPC o JSON-RPC son las opciones naturales porque interactúan directamente con el nodo. Para obtener un objeto con campos anidados, GraphQL suele ser más eficiente porque evita múltiples idas y vueltas. Para transmitir checkpoints, el servicio de ledger/stream (típicamente expuesto mediante streaming gRPC) es la herramienta adecuada. Para agregación histórica, GraphQL o un indexador suelen ser lo mejor.

• Enviar/inspeccionar una transacción → gRPC o JSON-RPC.
• Obtener un objeto con campos anidados → GraphQL.
• Transmitir checkpoints → servicio de ledger/stream (streaming gRPC).
• Agregación histórica → GraphQL o indexador.
• Notificaciones push en tiempo real → canal de suscripción (WebSocket), no ninguna de las tres superficies de solicitud/respuesta.

Advertencia de consistencia entre superficies

Dado que GraphQL está respaldado por indexador, la misma consulta lógica puede devolver datos en una posición de cadena ligeramente diferente a una lectura directa del nodo. Si mezclas superficies en un flujo crítico para la consistencia—por ejemplo, leer un objeto vía GraphQL y luego enviar una transacción vía gRPC—puedes observar un estado que está detrás de la punta. Esto no es un error; es una propiedad inherente de una superficie respaldada por indexador.

Para evitar inconsistencias, fija checkpoints. Lee el último número de secuencia de checkpoint desde una superficie de nodo directa (gRPC o JSON-RPC), luego usa ese checkpoint como límite de consistencia para tus consultas GraphQL. Alternativamente, mantén los flujos críticos para la consistencia en una sola superficie. El servicio de stream de checkpoints y ledger de Sui proporciona una forma de observar los checkpoints a medida que se producen.

No asumas que todas las superficies están en la misma posición de cadena en el mismo tiempo de reloj. Trata la frescura como una propiedad por superficie y diseña tu aplicación en consecuencia.

• GraphQL puede retrasarse respecto a la punta porque está respaldado por indexador.
• Fija checkpoints al mezclar superficies en flujos críticos para la consistencia.
• Mantén los flujos críticos para la consistencia en una sola superficie cuando sea posible.
• Trata la frescura como una propiedad por superficie.

Comparación ejecutable en Node.js: JSON-RPC vs GraphQL

El siguiente script de Node.js ejecuta una operación lógica—obtener el mismo objeto—mediante una llamada JSON-RPC y mediante una consulta GraphQL. Imprime las idas y vueltas y la forma de la respuesta para cada una. Reemplaza las URL de los puntos finales y el ID del objeto con valores de tu proveedor. Este ejemplo utiliza la API fetch integrada disponible en Node.js moderno.

El script mide el tiempo de reloj de cada llamada e imprime la respuesta JSON. No afirma que una superficie sea más rápida; te da un método reproducible para comparar en tu propio punto final. Ejecútalo contra los puntos finales JSON-RPC y GraphQL de tu proveedor y registra los resultados en la tabla de la siguiente sección.

// compare-jsonrpc-graphql.js
// Run with: node compare-jsonrpc-graphql.js

const JSONRPC_URL = 'https://your-provider.example/sui-jsonrpc';
const GRAPHQL_URL = 'https://your-provider.example/sui-graphql';
const OBJECT_ID = '0xYOUR_OBJECT_ID';

async function fetchJsonRpc() {
  const body = {
    jsonrpc: '2.0',
    id: 1,
    method: 'sui_getObject',
    params: [OBJECT_ID, { showType: true, showOwner: true, showContent: true }]
  };
  const start = Date.now();
  const res = await fetch(JSONRPC_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  const json = await res.json();
  const elapsed = Date.now() - start;
  console.log('JSON-RPC round-trips: 1');
  console.log('JSON-RPC elapsed ms:', elapsed);
  console.log('JSON-RPC response shape:', JSON.stringify(json).slice(0, 200));
  return json;
}

async function fetchGraphQL() {
  const query = `
    query GetObject($id: SuiAddress!) {
      object(address: $id) {
        address
        version
        digest
        asMoveObject {
          contents { type { repr } }
        }
      }
    }
  `;
  const start = Date.now();
  const res = await fetch(GRAPHQL_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ query, variables: { id: OBJECT_ID } })
  });
  const json = await res.json();
  const elapsed = Date.now() - start;
  console.log('GraphQL round-trips: 1');
  console.log('GraphQL elapsed ms:', elapsed);
  console.log('GraphQL response shape:', JSON.stringify(json).slice(0, 200));
  return json;
}

(async () => {
  await fetchJsonRpc();
  await fetchGraphQL();
})();

Comparación ejecutable en Node.js: cliente gRPC (opcional)

Si tu proveedor expone gRPC y has generado el cliente a partir de los archivos .proto, puedes extender la comparación para incluir la superficie gRPC. El siguiente fragmento asume que tienes un cliente generado y un punto final gRPC en ejecución. Obtiene el mismo objeto e imprime las idas y vueltas y la forma de la respuesta. Dado que gRPC requiere generación de código, este ejemplo es ilustrativo; adáptalo a la API de tu cliente generado.

El objetivo no es declarar un ganador sino darte un método reproducible para medir idas y vueltas, bytes, tipado y frescura contra tu propio punto final. Registra tus observaciones en la tabla de resultados de la siguiente sección.

// compare-grpc.js (illustrative; requires generated client)
// Run with: node compare-grpc.js

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const PROTO_PATH = './sui.proto';
const GRPC_URL = 'your-provider.example:443';
const OBJECT_ID = '0xYOUR_OBJECT_ID';

const packageDefinition = protoLoader.loadSync(PROTO_PATH, {
  keepCase: true,
  longs: String,
  enums: String,
  defaults: true,
  oneofs: true
});
const suiProto = grpc.loadPackageDefinition(packageDefinition);

const client = new suiProto.sui.rpc.v2.LedgerService(
  GRPC_URL,
  grpc.credentials.createSsl()
);

const start = Date.now();
client.getObject({ objectId: OBJECT_ID }, (err, response) => {
  const elapsed = Date.now() - start;
  if (err) {
    console.error('gRPC error:', err.message);
    return;
  }
  console.log('gRPC round-trips: 1');
  console.log('gRPC elapsed ms:', elapsed);
  console.log('gRPC response shape:', JSON.stringify(response).slice(0, 200));
});

Tabla de resultados reproducible para tu propio punto final

Utiliza la siguiente tabla para registrar tus propias mediciones. Ejecuta los scripts anteriores contra los puntos finales de tu proveedor y completa cada fila. No te bases en números de referencia publicados; mide contra el punto final que realmente usas, porque la latencia, el rendimiento y la frescura varían según el proveedor, la región y la versión de la red.

Para cada tarea, anota la superficie utilizada, el número de idas y vueltas, los bytes aproximados de la respuesta, si la respuesta está tipada, la frescura relativa a la punta de la cadena y cualquier nota. Esto te da un registro reproducible que puedes compartir con tu equipo o revisar cuando tu proveedor cambie las superficies admitidas.

• Tarea: la operación lógica que realizaste (p. ej., obtener objeto, enviar transacción).
• Superficie utilizada: JSON-RPC, gRPC o GraphQL.
• Idas y vueltas: número de llamadas de red requeridas.
• Bytes: tamaño aproximado de la respuesta.
• ¿Tipado?: si la respuesta está verificada por tipos (gRPC sí, JSON-RPC no, GraphQL con tipos de esquema).
• Frescura vs punta: qué tan detrás de la punta de la cadena estaba la respuesta.
• Notas: cualquier advertencia o error específico del proveedor.

Limitaciones y compensaciones entre superficies

La disponibilidad de superficies varía según el proveedor y la versión de la red. Algunos proveedores exponen las tres superficies; otros exponen un subconjunto. JSON-RPC está siendo eliminado gradualmente con el tiempo, por lo que el trabajo nuevo debería preferir gRPC o GraphQL cuando estén disponibles. GraphQL puede retrasarse respecto a la punta porque está respaldado por indexador. Ninguna de las tres reemplaza a un canal de suscripción para push en tiempo real; para eso, usa una superficie de suscripción WebSocket como la descrita en la guía Suscripciones WebSocket de RPC de Sui.

No hay una única superficie que sea mejor para todas las tareas. JSON-RPC es universal pero más verboso y desenfatizado. gRPC es tipado y eficiente pero requiere generación de código y HTTP/2. GraphQL es flexible y expresivo pero respaldado por indexador y potencialmente obsoleto. La elección correcta depende de tu tarea, tus requisitos de consistencia y las superficies admitidas por tu proveedor.

Al evaluar proveedores, considera las superficies que exponen, sus características de frescura documentadas y su modelo de precios. La página de precios de RPC y la página de servicio de API describen las ofertas de OnFinality; siempre verifica el soporte actual de superficies y los límites con tu proveedor.

• La disponibilidad varía según el proveedor y la versión de la red.
• JSON-RPC está siendo eliminado gradualmente; prefiere gRPC/GraphQL para trabajo nuevo.
• GraphQL puede retrasarse respecto a la punta; fija checkpoints para consistencia.
• Ninguna de las tres reemplaza a un canal de suscripción para push en tiempo real.

Solución de problemas comunes de selección de superficie

Si ves datos obsoletos de GraphQL, verifica si estás leyendo en la punta. GraphQL está respaldado por indexador, por lo que una consulta inmediatamente después de una transacción puede no reflejarla. Fija un checkpoint o espera a que el indexador se ponga al día. Si necesitas lecturas consistentes con la punta, usa gRPC o JSON-RPC.

Si tu cliente gRPC no puede conectarse, verifica que tu entorno de ejecución admita HTTP/2 y que hayas generado el cliente a partir de los archivos .proto correctos. Algunos proveedores requieren TLS; otros pueden usar un puerto diferente. Si los métodos JSON-RPC devuelven errores, verifica si el método es compatible con tu proveedor y si ha sido deprecado. El comportamiento específico del proveedor está documentado pero varía, así que consulta la documentación de tu proveedor.

Si estás mezclando superficies y ves resultados inconsistentes, aísla el flujo a una sola superficie o fija checkpoints entre superficies. Registra tus observaciones en la tabla de resultados para que puedas reproducir y diagnosticar el problema.

• Datos obsoletos de GraphQL: fija checkpoints o usa gRPC/JSON-RPC para lecturas en la punta.
• Fallos de conexión gRPC: verifica soporte HTTP/2, generación de código, TLS y puerto.
• Errores JSON-RPC: verifica el soporte del método y el estado de deprecación.
• Flujos mixtos inconsistentes: aísla a una superficie o fija checkpoints.

Próximos pasos para construir sobre Sui

Comienza identificando las superficies que expone tu proveedor. Luego asigna tus tareas a la tabla de decisión anterior y ejecuta los scripts de comparación contra tu punto final. Registra tus resultados y revísalos cuando tu proveedor cambie las superficies admitidas o cuando se actualicen las versiones de la red Sui.

Para inmersiones más profundas, lee la guía de la API gRPC de Sui, la superficie de consulta de la API GraphQL de Sui y la guía del servicio de stream de checkpoints y ledger de Sui. Para push en tiempo real, consulta la guía de Suscripciones WebSocket de RPC de Sui. Para detalles específicos del proveedor, consulta la guía RPC de Sui (RPC Assistant) y la página de red Sui.

A medida que construyes, mantén explícitos los requisitos de consistencia. Fija checkpoints al mezclar superficies, prefiere gRPC o GraphQL para trabajo nuevo y usa canales de suscripción para push en tiempo real. El centro de aprendizaje de OnFinality recopila guías relacionadas, y la página de servicio de API describe cómo comenzar con puntos finales gestionados.

• Identifica las superficies admitidas por tu proveedor.
• Asigna tareas a la tabla de decisión y mide con los scripts.
• Prefiere gRPC o GraphQL para trabajo nuevo; usa suscripciones para push.
• Fija checkpoints al mezclar superficies en flujos críticos para la consistencia.