API de Sui: Cómo elegir la interfaz adecuada para tu dApp

El panorama de la API de Sui está cambiando. Durante años, los desarrolladores interactuaron con la red a través de JSON-RPC, pero la Fundación Sui ha anunciado un cronograma de desaprobación que hace que gRPC y GraphQL sean los caminos recomendados. Si estás buscando "api de sui", probablemente intentas averiguar qué interfaz usar, cómo conectarte y qué hacer con el retiro de JSON-RPC.

Esta guía corta el ruido. Aprenderás las diferencias entre las interfaces de API de Sui, obtendrás ejemplos prácticos de código y entenderás cómo elegir la adecuada para tu proyecto. También te mostraremos cómo la infraestructura gestionada de Sui de OnFinality puede simplificar tu acceso.

Guía de decisión: ¿Qué API de Sui deberías usar?

Antes de entrar en detalles, aquí tienes un marco rápido para ayudarte a decidir qué interfaz de API de Sui se adapta a tus necesidades:

Si estás comenzando un nuevo proyecto, elige GraphQL o gRPC. JSON-RPC está desaprobado y se deshabilitará en los nodos completos de la red principal de la Fundación Sui a finales de julio de 2026. Construir sobre una interfaz desaprobada significa que tendrás que migrar pronto.

Si tienes una integración JSON-RPC existente, planifica tu migración ahora. El cronograma es claro: JSON-RPC se deshabilitará en los nodos completos de la red principal de la Fundación Sui para la semana del 27 de julio de 2026, con la eliminación completa del código para mediados de octubre de 2026. Comienza a evaluar gRPC o GraphQL hoy.

Si necesitas una solución gestionada, considera OnFinality. OnFinality proporciona endpoints RPC de Sui confiables tanto para la red principal como para la de prueba, manejando la infraestructura para que puedas concentrarte en construir. Consulta nuestra página de la red Sui para más detalles.

Entendiendo las interfaces de API de Sui

Sui ofrece tres interfaces de API principales, cada una con sus propias fortalezas:

JSON-RPC (Desaprobado)

JSON-RPC ha sido el estándar para interactuar con Sui. Es un protocolo simple basado en HTTP que usa JSON para solicitudes y respuestas. La mayoría de las herramientas y SDK de Sui existentes usan JSON-RPC.

Ejemplo de solicitud JSON-RPC:

curl -X POST https://rpc.sui.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getAllBalances",
    "params": ["0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961"]
  }'

Por qué está desaprobado: La Fundación Sui se está moviendo a protocolos más eficientes y escalables. Las limitaciones de JSON-RPC en transmisión y rendimiento llevaron a esta decisión.

gRPC

gRPC es un marco RPC de alto rendimiento y código abierto que utiliza Protocol Buffers para la serialización. Soporta transmisión bidireccional, lo que lo hace ideal para datos en tiempo real y aplicaciones de alto rendimiento.

Ejemplo de cliente gRPC (Node.js):

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const packageDefinition = protoLoader.loadSync('sui.proto');
const suiProto = grpc.loadPackageDefinition(packageDefinition);

const client = new suiProto.sui.NodeService('https://rpc.sui.io', grpc.credentials.createSsl());

client.getLatestCheckpointSequenceNumber({}, (err, response) => {
  if (err) {
    console.error(err);
  } else {
    console.log('Latest checkpoint:', response);
  }
});

Por qué elegir gRPC: Está diseñado para el rendimiento, con menor latencia y mayor rendimiento que JSON-RPC. También está fuertemente tipado, lo que reduce errores.

GraphQL

GraphQL es un lenguaje de consulta que permite a los clientes solicitar exactamente los datos que necesitan. Es ideal para aplicaciones de frontend donde quieres minimizar la transferencia de datos y simplificar la lógica del lado del cliente.

Ejemplo de consulta GraphQL:

query {
  address(address: "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961") {
    balance
    coins {
      nodes {
        coinType
        balance
      }
    }
  }
}

Por qué elegir GraphQL: Proporciona una forma flexible y eficiente de consultar datos en cadena. Puedes obtener múltiples recursos en una sola solicitud, reduciendo la sobrecarga de red.

Conectándose a Sui con OnFinality

OnFinality proporciona endpoints RPC de Sui gestionados tanto para la red principal como para la de prueba. Esto significa que no tienes que ejecutar tu propio nodo completo y obtienes acceso confiable y escalable a la red.

Endpoint RPC de la red principal de Sui:

https://rpc.sui.io

Endpoint RPC de la red de prueba de Sui:

https://rpc.testnet.sui.io

Estos endpoints soportan transportes HTTP y WebSocket. Para aplicaciones de producción, querrás usar un endpoint dedicado con límites de tasa más altos. Consulta nuestra página de precios para más detalles.

Ejemplos de código: Haciendo tu primera llamada a la API de Sui

Veamos un ejemplo simple usando JavaScript para obtener el saldo de una dirección de Sui.

Usando JSON-RPC (Temporal)

const axios = require('axios');

const url = 'https://rpc.sui.io';
const address = '0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961';

const payload = {
  jsonrpc: '2.0',
  id: 1,
  method: 'suix_getAllBalances',
  params: [address]
};

axios.post(url, payload)
  .then(response => {
    console.log(response.data.result);
  })
  .catch(error => {
    console.error(error);
  });

Usando GraphQL (Recomendado)

const axios = require('axios');

const url = 'https://rpc.sui.io/graphql';
const query = `
  query {
    address(address: "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961") {
      balance
    }
  }
`;

axios.post(url, { query })
  .then(response => {
    console.log(response.data.data);
  })
  .catch(error => {
    console.error(error);
  });

Errores comunes y cómo evitarlos

1. Usar JSON-RPC desaprobado para nuevos proyectos. Evita esto. Comienza con GraphQL o gRPC para ahorrarte una migración más adelante.
2. No manejar los límites de tasa. Los endpoints públicos tienen límites de tasa. Para producción, usa un proveedor gestionado como OnFinality para obtener límites más altos y recursos dedicados.
3. Ignorar el soporte de WebSocket. Para actualizaciones en tiempo real (por ejemplo, notificaciones de transacciones), usa WebSocket. OnFinality soporta WebSocket en sus endpoints.
4. Olvidar la red de prueba. Siempre prueba tu integración en la red de prueba primero. OnFinality proporciona un endpoint de red de prueba de Sui para este propósito.

Ruta de migración de JSON-RPC a gRPC o GraphQL

Si tienes una integración JSON-RPC existente, aquí tienes un plan paso a paso:

1. Audita tu uso actual. Identifica qué métodos JSON-RPC usas y mapearlos a equivalentes de gRPC o GraphQL.
2. Elige tu interfaz objetivo. Para servicios de backend, gRPC suele ser la mejor opción. Para frontends, GraphQL es más flexible.
3. Configura un entorno de prueba. Usa la red de prueba de Sui para experimentar con la nueva interfaz.
4. Refactoriza tu código. Actualiza tus SDK y bibliotecas. Los SDK de Sui se están actualizando para soportar gRPC y GraphQL.
5. Prueba a fondo. Asegúrate de que toda la funcionalidad funcione como se espera.
6. Implementa y monitorea. Realiza la migración gradualmente, monitoreando errores.

Conclusiones clave

• Sui ofrece tres interfaces de API: JSON-RPC (desaprobado), gRPC y GraphQL.
• JSON-RPC se deshabilitará a finales de julio de 2026, así que planifica tu migración ahora.
• Elige gRPC para servicios de backend y GraphQL para aplicaciones de frontend.
• OnFinality proporciona endpoints RPC de Sui gestionados para la red principal y de prueba, simplificando tu infraestructura.
• Siempre prueba en la red de prueba antes de implementar en la red principal.

Preguntas frecuentes

¿Qué es la API de Sui?

La API de Sui se refiere al conjunto de interfaces que permiten a los desarrolladores interactuar con la cadena de bloques de Sui. Incluye JSON-RPC, gRPC y GraphQL.

¿Está desaprobado JSON-RPC en Sui?

Sí, la Fundación Sui ha anunciado que JSON-RPC será desaprobado y deshabilitado en los nodos completos de la red principal a finales de julio de 2026.

¿Qué API de Sui debería usar?

Para nuevos proyectos, usa GraphQL para frontend y gRPC para servicios de backend. JSON-RPC solo es adecuado para integraciones temporales o heredadas.

¿OnFinality soporta Sui?

Sí, OnFinality proporciona endpoints RPC de Sui gestionados tanto para la red principal como para la de prueba. Visita nuestra página de la red Sui para más información.

¿Cómo obtengo una clave de API de Sui?

Con OnFinality, puedes registrarte y obtener claves de API para los endpoints de Sui. Consulta nuestra página de precios para más detalles.

¿Cuáles son los límites de tasa para la API de Sui?

Los límites de tasa varían según el proveedor y el plan. OnFinality ofrece planes flexibles con diferentes límites de tasa. Contáctanos para detalles específicos.

¿Puedo usar WebSocket con la API de Sui?

Sí, Sui soporta WebSocket para datos en tiempo real. Los endpoints de OnFinality soportan conexiones WebSocket.

¿Cómo migro de JSON-RPC a gRPC?

Sigue la ruta de migración descrita anteriormente. La Fundación Sui proporciona una Guía de migración de JSON-RPC con pasos detallados.

¿Qué es SuiJSON?

SuiJSON es un formato basado en JSON que alinea las entradas JSON con los argumentos de llamada de Move. Tiene reglas específicas de coerción de tipos para garantizar la compatibilidad con los tipos de Move.

¿Dónde puedo encontrar la referencia de la API de Sui?

La Referencia oficial de la API de Sui proporciona documentación completa para los métodos JSON-RPC. Para gRPC y GraphQL, consulta la Documentación de Sui.