¿Qué es JSON-RPC? Protocolo, ejemplos y comparación con REST

¿Qué es JSON-RPC?

JSON-RPC es un protocolo ligero de llamada a procedimiento remoto (RPC) que codifica peticiones y respuestas en JSON. El cliente indica un método y sus parámetros, el servidor lo ejecuta y devuelve un resultado o un error. No tiene estado y es independiente del transporte: la especificación JSON-RPC 2.0 (de 2010) describe los mensajes, no cómo viajan.

Lo encontrarás en los nodos de Ethereum, en el Language Server Protocol que usan los editores de código y en el Model Context Protocol de las herramientas de IA. Los tres usan mensajes JSON-RPC 2.0.

Cómo funciona una llamada JSON-RPC

Una petición tiene cuatro miembros: jsonrpc (siempre "2.0"), method (el nombre que se llama), params (opcional, un array para argumentos posicionales o un objeto para argumentos con nombre) e id (una cadena o un número que eliges tú y que vuelve en la respuesta).

{"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

Una respuesta correcta lleva el mismo id y un result:

{"jsonrpc": "2.0", "result": 19, "id": 1}

Una llamada fallida lleva un objeto error con un code numérico y un message en lugar del resultado:

{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": 1}

Sobre HTTP es un único POST a una URL fija, con el nombre del método en el cuerpo y no en la ruta. Puedes probarlo con curl: envía el objeto de la petición como cuerpo con Content-Type: application/json.

Notificaciones y peticiones por lotes

Una petición sin id es una notificación: el servidor no debe responder, así que el cliente nunca sabe si funcionó.

{"jsonrpc": "2.0", "method": "log", "params": {"level": "info"}}

Para enviar varias llamadas a la vez, mete los objetos de petición en un array. El servidor responde con un array de respuestas, y la especificación permite cualquier orden, así que empareja cada respuesta con su petición por el id.

[
  {"jsonrpc": "2.0", "method": "sum", "params": [1, 2, 4], "id": 1},
  {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 2}
]

Códigos de error estándar

JSON-RPC frente a REST y gRPC

Elige REST cuando tu API gira en torno a recursos y quieres que la caché y los códigos de estado de HTTP trabajen a tu favor. Elige JSON-RPC cuando el modelo natural es "haz esta acción", por ejemplo enviar una transacción o pedir completados a un servidor de lenguaje.

Errores habituales

• Dar por buena una respuesta HTTP 200. Muchos servidores devuelven 200 aunque el cuerpo contenga un error. Revisa el cuerpo.
• Reutilizar un id dentro de una conexión. No se pueden emparejar las respuestas, lo que molesta sobre todo en los lotes.
• Suponer que las respuestas de un lote llegan en orden. La especificación no lo garantiza.
• Enviar como notificación una llamada que necesita respuesta. Sin id nunca verás el resultado ni el error.
• Usar null como id. La especificación lo desaconseja y MCP lo prohíbe.
• Meter credenciales en el contenido. Autentica en la capa de transporte, por ejemplo con un bearer token en la cabecera Authorization.

Pruebas y monitorización de endpoints JSON-RPC

Como los errores suelen llegar con estado 200, una comprobación de estado simple no los detecta. Valida el cuerpo: que no haya error, que exista result y que el id coincida. La monitorización de API de LoadFocus admite aserciones sobre código de estado, cuerpo y tiempo de respuesta, y los checks gratuitos se ejecutan cada 5 minutos.

En las pruebas de carga, ten en cuenta que un lote es una sola petición HTTP pero muchas llamadas a métodos, así que carga tu backend de forma distinta que las mismas llamadas enviadas una a una. Usa ids únicos por llamada y prueba primero los métodos que tocan tu base de datos o un nodo de blockchain. Las pruebas de carga de LoadFocus ejecutan scripts de JMeter y k6 que pueden enviar cuerpos JSON, y esta guía sobre pruebas de carga de APIs explica la configuración. La entrada sobre el endpoint de una API aclara a qué apuntas con la prueba.

Preguntas frecuentes: JSON-RPC

¿Se sigue usando JSON-RPC?

Sí. Los clientes de Ethereum exponen una interfaz JSON-RPC, el Language Server Protocol lo usa entre el editor y el servidor de lenguaje, y el Model Context Protocol se apoya en JSON-RPC 2.0. Es menos habitual en las APIs web públicas, donde domina REST.

JSON-RPC o REST: ¿cuál es mejor?

Ninguno en general. REST encaja en APIs públicas orientadas a recursos. JSON-RPC encaja en interfaces orientadas a acciones donde llamas a un método, y funciona sobre transportes distintos de HTTP.

¿JSON-RPC usa códigos de estado HTTP?

La especificación no los define. Los errores van en el cuerpo de la respuesta y muchos servidores devuelven 200 en ambos casos. Algunas implementaciones traducen los errores a códigos HTTP, así que consulta la documentación del servidor.

¿Cómo autentico una API JSON-RPC?

El protocolo no tiene autenticación propia. Usa lo que ofrezca el transporte: una clave de API o un bearer token en una cabecera sobre HTTP, o un mecanismo a nivel de conexión con WebSocket.

¿Qué diferencia hay entre JSON-RPC 1.0 y 2.0?

La versión 2.0 identifica los mensajes con el miembro jsonrpc y marca una notificación omitiendo el id (la 1.0 usaba un id nulo). Además define parámetros con nombre, peticiones por lotes y un rango reservado de códigos de error. Las dos versiones pueden no ser compatibles, así que usa la 2.0 para todo lo nuevo.

¿Puede JSON-RPC enviar datos desde el servidor?

Sobre una conexión persistente como WebSocket, sí: ambos lados pueden enviar notificaciones. Sobre HTTP simple, solo el cliente inicia una petición.