APIs de blockchain: arquitectura, implementación y verificación

Respuesta directa y alcance

Una API de blockchain es cualquier interfaz programática que permite a una aplicación leer o escribir en una red blockchain sin ejecutar su propio nodo. El término abarca al menos tres capas distintas: endpoints JSON-RPC sin procesar que exponen métodos del nodo, APIs de datos indexados que preprocesan el estado de la cadena en esquemas consultables, y APIs de pasarela que envuelven operaciones comunes como saldos de tokens o envío de transacciones.

Este artículo se centra en cómo difieren estas capas, cómo integrarlas correctamente y cómo verificar que lo que recibe es preciso y actual. No recomienda un proveedor específico para cada red; para elecciones concretas de endpoints y proveedores, utilice el Asistente de RPC o explore las redes compatibles.

• JSON-RPC sin procesar: lo más cercano al nodo, métodos estándar, usted se encarga de la decodificación y la indexación.
• APIs de datos indexados: tablas preprocesadas, más rápidas para consultas históricas, pero con retraso de indexación.
• APIs de pasarela: superficies REST o GraphQL simplificadas, convenientes pero menos transparentes sobre la frescura.

Requisitos previos y supuestos

Los ejemplos asumen que tiene una URL de endpoint RPC para una cadena compatible con EVM y, opcionalmente, una clave de API para un servicio de datos indexados. Reemplace RPC_URL y API_KEY con sus propios valores. No se codifica ningún endpoint público porque los endpoints públicos a menudo limitan la tasa o cambian sin previo aviso.

Debe sentirse cómodo con solicitudes HTTP, JSON y herramientas básicas de línea de comandos. Los ejemplos en Python utilizan solo la biblioteca estándar para que se ejecuten sin instalar paquetes. Si es nuevo en el acceso a nodos, comience con la guía de endpoints RPC antes de continuar.

Modelo mental: tres capas de acceso a blockchain

Piense en el acceso a blockchain como una pila. En la parte inferior, un nodo mantiene el estado canónico de la cadena y expone métodos JSON-RPC como eth_blockNumber, eth_getBalance y eth_getLogs. Esta capa es autoritativa pero sin procesar: debe saber qué bloque consultar y cómo decodificar los resultados.

Por encima, los indexadores consumen bloques y escriben datos derivados en bases de datos. Una API indexada podría responder "todas las transferencias del token X en las últimas 24 horas" en una sola solicitud, mientras que RPC sin procesar requeriría escanear registros en muchos bloques. La contrapartida es el retraso de indexación: la vista indexada puede ir por detrás de la cabeza de la cadena por segundos o minutos.

En la parte superior, las APIs de pasarela combinan múltiples fuentes detrás de una interfaz simplificada. Son convenientes para prototipos pero pueden ocultar a qué altura de bloque corresponde una respuesta. Para casos de uso financieros o de cumplimiento, confirme siempre el contexto de bloque de cualquier respuesta.

Solicitud JSON-RPC ejecutable y verificación de respuesta

El siguiente comando curl consulta el número de bloque más reciente y luego el saldo de una dirección en ese bloque. Ejecútelo en una terminal y compare el número de bloque devuelto con un explorador de bloques.

Una respuesta correcta contiene un campo result con un número de bloque hexadecimal. Si recibe un objeto de error en su lugar, verifique la URL del endpoint, los encabezados de autenticación y el nombre del método.

curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

# Then query balance at that block (replace BLOCK_HEX and ADDRESS)
curl -s -X POST "$RPC_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_getBalance","params":["ADDRESS","BLOCK_HEX"]}'

Cliente Python con consultas fijadas a un bloque

Fijar las consultas a una altura de bloque específica hace que los resultados sean reproducibles. El script siguiente obtiene el último bloque y luego solicita el saldo en ese bloque exacto. También imprime el número de bloque para que pueda verificarlo con un explorador.

Este patrón es esencial para pruebas y para cualquier flujo de trabajo donde la consistencia importe. Si consulta "latest" dos veces, puede obtener bloques diferentes y, por lo tanto, saldos diferentes.

import json, urllib.request, os

RPC_URL = os.environ["RPC_URL"]
ADDRESS = "0x0000000000000000000000000000000000000000"

def rpc(method, params):
    payload = json.dumps({"jsonrpc":"2.0","id":1,"method":method,"params":params}).encode()
    req = urllib.request.Request(RPC_URL, data=payload, headers={"Content-Type":"application/json"})
    with urllib.request.urlopen(req, timeout=10) as resp:
        body = json.loads(resp.read())
    if "error" in body:
        raise RuntimeError(body["error"])
    return body["result"]

block_hex = rpc("eth_blockNumber", [])
balance_hex = rpc("eth_getBalance", [ADDRESS, block_hex])
print("block:", int(block_hex, 16))
print("balance wei:", int(balance_hex, 16))

Patrón de solicitud a API de datos indexados

Las APIs indexadas suelen utilizar REST o GraphQL. El ejemplo siguiente utiliza un patrón REST genérico con marcadores de posición. El paso clave de verificación es comprobar si la respuesta incluye una altura de bloque o una marca de tiempo, y si esa altura está cerca de la cabeza de la cadena.

Si la respuesta carece de contexto de bloque, trátela como una vista de conveniencia en lugar de un registro autoritativo. Para liquidación o contabilidad, verifique de forma cruzada con RPC sin procesar en un bloque conocido.

curl -s "https://INDEXER_API_URL/v1/transfers?address=ADDRESS&limit=10" \
  -H "Authorization: Bearer $API_KEY"

# Inspect the response for a block number or timestamp field.
# Compare that height with eth_blockNumber from your RPC endpoint.

Procedimiento de medición y tabla de resultados

Las afirmaciones de latencia de los proveedores son difíciles de comparar porque dependen de su ubicación, tipo de solicitud y tamaño de carga útil. Mida desde su propio entorno. Ejecute al menos 100 solicitudes secuenciales para cada método y registre la latencia mediana y el percentil 95. También registre la altura de bloque devuelta al inicio y al final de la ejecución para detectar retrasos.

Utilice una tabla como la siguiente para registrar sus resultados. No complete números de este artículo; estos son marcadores de posición para sus propias mediciones.

Ejecute la medición a la misma hora del día en todos los endpoints para reducir el sesgo diurno. Si necesita capacidad dedicada para obtener resultados consistentes, revise las opciones de nodos dedicados y los precios de RPC.

Solución de problemas comunes de integración

La mayoría de los fallos de API de blockchain se engloban en unas pocas categorías: autenticación, limitación de tasa, parámetros mal formados y datos obsoletos. El orden de diagnóstico a continuación va de las comprobaciones más baratas a las más costosas.

Si recibe HTTP 401 o 403, verifique la clave de API y el formato del encabezado. Si recibe HTTP 429, ha alcanzado un límite de tasa; retroceda con retroceso exponencial y considere un nivel superior o un endpoint dedicado. Si recibe un error JSON-RPC con código -32602, sus parámetros no son válidos; verifique las sumas de comprobación de direcciones y las etiquetas de bloque. Si las respuestas son válidas pero obsoletas, compare la altura de bloque devuelta con un explorador público.

• Verifique el estado HTTP antes de analizar el JSON.
• Registre el código y el mensaje de error JSON-RPC, no solo la excepción.
• Fije las consultas a una altura de bloque cuando la consistencia importe.
• Compare los datos indexados con RPC sin procesar en la misma altura.

Limitaciones y compensaciones

RPC sin procesar le brinda autoridad y flexibilidad, pero traslada el trabajo de indexación y decodificación a su aplicación. Las APIs indexadas reducen la complejidad de las consultas pero introducen retraso y esquemas específicos del proveedor. Las APIs de pasarela son las más rápidas de integrar pero las menos transparentes sobre la procedencia de los datos.

Ninguna capa única es correcta para todos los casos de uso. Una billetera podría usar RPC sin procesar para verificar saldos y un indexador para el historial de transacciones. Un sistema de trading podría requerir nodos dedicados para controlar la latencia. Documente de qué capa depende cada función para que pueda razonar sobre los modos de fallo.

Próximos pasos

Comience fijando una consulta crítica a una altura de bloque y verificándola con un explorador. Luego agregue un segundo endpoint y ejecute el procedimiento de medición anterior. Si necesita ayuda para seleccionar un endpoint para una red específica, consulte el Asistente de RPC. Para una planificación de infraestructura más amplia, lea la guía de alojamiento de nodos de blockchain y la guía de endpoints RPC multicadena.