Vista general
JSON-RPC es un protocolo de llamada a procedimiento remoto (RPC) ligero y sin estado. Principalmente, esta especificación define diversas estructuras de datos y las reglas en torno a su procesamiento. Es agnóstico en cuanto al transporte, puesto que los conceptos pueden usarse dentro del mismo proceso, a través de sockets, http o en diversos entornos de paso de mensajes. Usa JSON (RFC 4627) como formato de datos.
Está diseñado para ser sencillo de usar.
Convenciones
Las palabras clave "DEBE", "NO DEBE", "REQUERIDO", "TIENE QUE", "NO TIENE QUE", "DEBERÍA", "NO DEBERÍA", "RECOMENDADO", "PUEDE" y "OPCIONAL" en este documento deben interpretarse como se describe en RFC 2119.
Dado que JSON-RPC emplea JSON, tiene el mismo sistema de tipos (véase http://www.json.org or RFC 4627). JSON puede representar cuatro tipos primitivos (Objeto, Matriz, Cadena, Número, Booleano, Nulo) y dos tipos estructurados (objetos y matrices). El término "Primitivo" en esta especificación hace referencia a cualquiera de esos cuatro tipos primitivos de JSON. El término "estructurado" hace referencia a cualquiera de los tipos JSON estructurados. Siempre que en este documento se mencione un tipo JSON, la primera letra irá siempre en mayúscula: Objeto, Matriz, Cadena, Número, Booleano, Nulo. Verdadero y Falso también se escriben en mayúsculas.
Todos los nombres de miembros intercambiados entre el Cliente y el Servidor que se tengan en cuenta para cualquier tipo de correspondencia deben diferenciarse entre mayúsculas y minúsculas. Los términos función, método y procedimiento pueden considerarse intercambiables.
El Cliente se define como el origen de los objetos de la Solicitud y el gestor de los objetos de Respuesta.
El Servidor se define como el origen de los objetos Respuesta y el gestor de los objetos Solicitud.
Una implementación de esta especificación podría desempeñar con facilidad ambos papeles, incluso al mismo tiempo, para otros clientes diferentes o para el mismo cliente. Esta especificación no aborda esa capa de complejidad.
Compatibilidad
Es posible que los objetos Solicitud y Respuesta JSON-RPC 2.0 no funcionen con los clientes o servidores JSON-RPC 1.0 existentes. No obstante, es fácil distinguir entre las dos versiones, ya que 2.0 siempre cuenta con un miembro llamado "jsonrpc" con un valor de Cadena "2.0", mientras que 1.0 no lo tiene. La mayoría de las implementaciones de la versión 2.0 deberían considerar la posibilidad de tratar los objetos de la versión 1.0, aunque no sean los aspectos P2P e indicación de clases de la versión 1.0.
Objeto de Solicitud
Una llamada rpc se realiza enviando un objeto de Solicitud a un Servidor. El objeto de Solicitud tiene los siguientes miembros:
jsonrpc: Cadena que especifica la versión del protocolo JSON-RPC. DEBE ser exactamente "2.0".
method: Cadena que contiene el nombre del método a invocar. Los nombres de métodos que empiezan por la palabra rpc seguida de un punto (U+002E o ASCII 46) están reservados para métodos internos de rpc y extensiones y NO DEBEN emplearse para nada más.
params: Valor estructurado que contiene los valores de los parámetros que se emplearán durante la invocación del método. Este miembro PUEDE omitirse.
id:
Un identificador establecido por el Cliente que DEBE contener un valor de Cadena, Número o NULO si se incluye. Si no se incluye se asume que es una notificación. El valor normalmente NO DEBERÍA ser NULO [1] y los Números NO DEBERÍAN contener partes fraccionarias [2].
El Servidor DEBE responder con el mismo valor en el objeto Respuesta si se incluye. Este miembro se emplea para correlacionar el contexto entre ambos objetos.
[1] Se desaconseja el uso de Nulo como valor para el miembro id en un objeto Solicitud, ya que esta especificación emplea un valor de Nulo para Respuestas con un id desconocido. Además, dado que JSON-RPC 1.0 usa un valor id de Nulo para las Notificaciones, esto podría causar confusión en su manejo.
[2] Las partes fraccionarias pueden resultar problemáticas, ya que muchas fracciones decimales no pueden representarse exactamente como fracciones binarias.
Notificación
Una Notificación es un objeto de Solicitud sin un miembro "id". Un objeto de Solicitud que es una Notificación significa la falta de interés del Cliente en el objeto de Respuesta correspondiente, y como tal no se debe devolver ningún objeto de Respuesta al cliente. El Servidor NO DEBE responder a una Notificación, incluidas las que se encuentran dentro de una solicitud por lotes.
Las Notificaciones no son confirmables por definición, puesto que no tienen un objeto de Respuesta que devolver. Como tal, el Cliente no sería consciente de ningún error (como, por ejemplo, "Parámetros no válidos", "Error interno").
Estructuras de parámetros
Si está presente, los parámetros para la llamada rpc DEBEN brindarse como un valor Estructurado. Ya sea por posición mediante una Matriz o por nombre mediante un Objeto.
-
por posición: los parámetros DEBEN ser una matriz que contenga los valores en el orden esperado por el servidor.
por nombre: los parámetros DEBEN ser un objeto, con nombres de miembros que coincidan con los nombres de parámetros esperados por el servidor. La ausencia de nombres esperados PUEDE generar un error. Los nombres DEBEN coincidir exactamente, incluyendo mayúsculas y minúsculas, con los parámetros esperados del método.
Objeto de respuesta
Cuando se realiza una llamada rpc, el Servidor DEBE responder con una Respuesta, excepto en el caso de las Notificaciones. La Respuesta se expresa como un único Objeto JSON, con los siguientes miembros:
jsonrpc: Cadena que especifica la versión del protocolo JSON-RPC. DEBE ser exactamente "2.0".
resultado: este miembro es OBLIGATORIO en caso de éxito.
Este miembro NO DEBE existir si se ha producido un error al invocar el método.
El valor de este miembro viene determinado por el método invocado en el Servidor.
error: este miembro es OBLIGATORIO en caso de error.
Este miembro NO DEBE existir si no se ha producido ningún error durante la invocación.
El valor de este miembro DEBE ser un objeto tal como se describe en la sección 5.1.
id: este miembro es OBLIGATORIO.
DEBE ser el mismo que el valor del miembro id en el objeto de solicitud.
Si se ha producido un error al detectar el id en el objeto de Solicitud (por ejemplo, error de análisis/Solicitud no válida), DEBE ser Nulo.
Se DEBE incluir el miembro de resultado o el miembro de error, pero NO se DEBEN incluir ambos miembros.
Objeto de error
Cuando una llamada rpc encuentra un error, el Objeto de Respuesta DEBE contener el miembro error con un valor que sea un Objeto con los siguientes miembros:
código: un número que indica el tipo de error que se ha producido.
DEBE ser un número entero..
mensaje: cadena que presenta una breve descripción del error.
El mensaje DEBERÍA limitarse a una sola frase concisa.
dato: Valor Primitivo o Estructurado que contiene información adicional acerca del error.
Puede omitirse.
El valor de este miembro lo define el Servidor (p. ej., información detallada de errores, errores anidados, etc.).
Los códigos de error comprendidos entre -32768 y -32000 están reservados para errores predefinidos. Cualquier código dentro de este rango, pero no definido de forma explícita a continuación, se reserva para uso futuro. Los códigos de error son prácticamente los mismos que los sugeridos para XML-RPC en la siguiente url: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php
| código | mensaje | significado |
|---|---|---|
| -32700 | Error de análisis | El servidor ha recibido un JSON no válido. Se ha producido un error en el servidor al analizar el texto JSON. |
| -32600 | Solicitud no válida | El JSON enviado no es un objeto de Solicitud válido. |
| -32601 | Método no encontrado | El método no existe/no está disponible. |
| -32602 | Parámetros no válidos | Parámetro(s) de método no válido(s). |
| -32603 | Error interno | Error interno JSON-RPC. |
| -32099 to -32000 | Error del servidor | Reservado para errores de servidor definidos por la implementación. |
El resto del espacio está disponible para errores definidos por la aplicación.
Lote
Para enviar diversos objetos de Solicitud al mismo tiempo, el Cliente PUEDE enviar una Matriz llena de objetos de Solicitud.
El Servidor debe responder con una Matriz que contenga los objetos de Respuesta correspondientes, después de que todos los objetos de Solicitud del lote hayan sido procesados. Un objeto de Respuesta DEBERÍA existir para cada objeto de Solicitud, excepto que NO DEBERÍA haber ningún objeto de Respuesta para notificaciones. El Servidor PUEDE procesar una llamada rpc por lotes como una serie de tareas concurrentes, procesándolas en cualquier orden y con cualquier ancho de paralelismo.
Los objetos de Respuesta que se devuelven de una llamada por lotes PUEDEN devolverse en cualquier orden dentro de la Matriz. El Cliente DEBERÍA hacer coincidir los contextos entre el conjunto de objetos de Solicitud y el conjunto obtenido de objetos de Respuesta basándose en el miembro id dentro de cada Objeto.
Si la propia llamada rpc por lotes no se reconoce como un JSON válido o como una Matriz con al menos un valor, la respuesta del Servidor DEBE ser un único objeto Respuesta. Si no hay objetos de Respuesta contenidos dentro de la matriz de Respuesta tal y como va a ser enviada al cliente, el servidor NO DEBE devolver una Matriz vacía y no debe devolver nada en absoluto.
Ejemplos:
Sintaxis:
--> datos enviados al Servidor <-- datos enviados al Cliente
llamada rpc con parámetros posicionales:
--> {"jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}
<-- {"jsonrpc": "2.0", "result": 19, "id": 1}
--> {"jsonrpc": "2.0", "method": "subtract", "params": [23, 42], "id": 2}
<-- {"jsonrpc": "2.0", "result": -19, "id": 2}
llamada rpc con parámetros con nombre:
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"subtrahend": 23, "minuend": 42}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 4}
<-- {"jsonrpc": "2.0", "result": 19, "id": 4}
una Notificación:
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}
--> {"jsonrpc": "2.0", "method": "foobar"}
llamada rpc de método inexistente:
--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}
<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Procedure not found."}, "id": "1"}
llamada rpc con JSON no válido:
--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}
llamada rpc con objeto de Solicitud no válido:
--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}
<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
Lote de llamada rpc, JSON no válido:
--> [ {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},{"jsonrpc": "2.0", "method" ]
<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error."}, "id": null}
rpc con una Matriz vacía:
--> []
<-- "jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
llamada rpc con un Lote no válido (pero no vacío):
--> [1]
<-- [ {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null} ]
llamada rpc con Lote no válido:
--> [1,2,3]
<-- [
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null}
]
Lote de llamada rpc:
--> [
{"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"},
{"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
{"jsonrpc": "2.0", "method": "subtract", "params": [42,23], "id": "2"},
{"foo": "boo"},
{"jsonrpc": "2.0", "method": "foo.get", "params": {"name": "myself"}, "id": "5"},
{"jsonrpc": "2.0", "method": "get_data", "id": "9"}
]
<-- [
{"jsonrpc": "2.0", "result": 7, "id": "1"},
{"jsonrpc": "2.0", "result": 19, "id": "2"},
{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request."}, "id": null},
{"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found."}, "id": "5"},
{"jsonrpc": "2.0", "result": ["hello", 5], "id": "9"}
]
Lote de llamadas rpc (todas las notificaciones):
--> [
{"jsonrpc": "2.0", "method": "notify_sum", "params": [1,2,4]},
{"jsonrpc": "2.0", "method": "notify_hello", "params": [7]},
]
<-- //No se devuelve nada para todos los lotes de notificación
Extensiones
Los nombres de métodos que comienzan por rpc. están reservados para extensiones del sistema, y NO DEBEN usarse para nada más. Cada extensión del sistema se define en una especificación relacionada. Todas las extensiones del sistema son OPCIONALES.
Copyright (C) 2007-2010 por el grupo de trabajo JSON-RPC
Este documento y sus traducciones pueden emplearse para implementar JSON-RPC, puede copiarse y facilitarse a terceros, y pueden prepararse, copiarse, publicarse y distribuirse, total o parcialmente, obras derivadas que lo comenten o expliquen de otro modo o que ayuden a su implementación, sin restricción de ningún tipo, siempre que en todas esas copias y obras derivadas se incluya el aviso de copyright anterior y este párrafo. Sin embargo, este documento no podrá modificarse en modo alguno.
Los permisos limitados concedidos con anterioridad son perpetuos y no se revocarán.
El presente documento y la información que contiene se facilitan "TAL CUAL" y se EXCLUYE CUALQUIER GARANTÍA, EXPRESA O IMPLÍCITA, INCLUIDA PERO NO LIMITADA A CUALQUIER GARANTÍA DE QUE EL USO DE LA INFORMACIÓN AQUÍ CONTENIDA NO INFRINGIRÁ NINGÚN DERECHO O CUALQUIER GARANTÍA IMPLÍCITA DE COMERCIABILIDAD O IDONEIDAD PARA UN PROPÓSITO PARTICULAR.