JSON-RPC es un protocolo de llamada a procedimiento remoto codificado en JSON . Es similar al protocolo XML-RPC , que define solo algunos tipos de datos y comandos. JSON-RPC permite notificaciones (datos enviados al servidor que no requieren respuesta) y el envío de múltiples llamadas al servidor que pueden ser respondidas de forma asincrónica.
Historia
Versión | Descripción | Con fecha de |
---|---|---|
1.0 | Versión original | 2005 |
1,1 WD | Borrador de trabajo . Agrega parámetros con nombre, agrega códigos de error específicos y agrega funciones de introspección. | 2006-08-07 |
1.1 Alt | Sugerencia para un JSON-RPC 1.1 simple . Propuesta alternativa a 1.1 WD. | 2007-05-06 |
1.1 Especificación de objeto | Especificación de objeto . Propuesta alternativa a 1.1 WD / 1.1ALT. | 2007-07-30 |
1.2 | Propuesta . Una revisión posterior de este documento se renombró a 2.0. | 2007-12-27 |
2.0 | Propuesta de especificación | 2009-05-24 |
2.0 (revisado-) | Especificación | 2010-03-26 |
Uso
JSON-RPC funciona enviando una solicitud a un servidor que implementa este protocolo. En ese caso, el cliente suele ser un software que intenta llamar a un método único de un sistema remoto. Se pueden pasar varios parámetros de entrada al método remoto como una matriz u objeto, mientras que el método en sí puede devolver varios datos de salida también. (Esto depende de la versión implementada).
Todos los tipos de transferencia son objetos únicos, serializados mediante JSON. [1] Una solicitud es una llamada a un método específico proporcionado por un sistema remoto. Puede contener tres miembros:
method
- Una cadena con el nombre del método que se invocará. Nombres de métodos que comienzan con "rpc". están reservados para métodos internos de rpc.params
- Un objeto o matriz de valores que se pasarán como parámetros al método definido. Este miembro puede omitirse.id
- Una cadena o un número no fraccionario que se utiliza para hacer coincidir la respuesta con la solicitud a la que responde. [2] Este miembro puede omitirse si no se debe devolver una respuesta. [3]
El receptor de la solicitud debe responder con una respuesta válida a todas las solicitudes recibidas. Una respuesta puede contener los miembros mencionados a continuación.
result
- Los datos devueltos por el método invocado. Este elemento tiene el formato de un objeto JSON-stat. Si se produjo un error al invocar el método, este miembro no debe existir. [4]error
- Un objeto de error si hubo un error al invocar el método; de lo contrario, este miembro no debe existir. [5] El objeto debe contener código de miembros (entero) y mensaje (cadena). [6] Un miembro de datos opcional puede contener más datos específicos del servidor. Hay códigos de error predefinidos que siguen a los definidos para XML-RPC.
id
- La identificación de la solicitud a la que está respondiendo.
Dado que hay situaciones en las que no se necesita o incluso se desea una respuesta, se introdujeron notificaciones. Una notificación es similar a una solicitud, excepto por la identificación, que no es necesaria porque no se devolverá ninguna respuesta. En este caso, la id
propiedad debe omitirse (Versión 2.0) o ser null
(Versión 1.0).
Ejemplos de
En estos ejemplos, -->
denota datos enviados a un servicio ( solicitud ), mientras que <--
denota datos provenientes de un servicio. Aunque a <--
menudo se le llama respuesta en la computación cliente-servidor, dependiendo de la versión de JSON-RPC no implica necesariamente una respuesta a una solicitud .
Versión 2.0
Solicitud y respuesta:
-> { "jsonrpc" : "2.0" , "método" : "restar" , "params" : { "minuendo" : 42 , "sustraendo" : 23 }, "id" : 3 } <- { "jsonrpc " : " 2.0 " , " resultado " : 19 , " id " : 3 }
Notificación (sin respuesta):
-> { "jsonrpc" : "2.0" , "método" : "actualización" , "params" : [ 1 , 2 , 3 , 4 , 5 ]}
Versión 1.1 (Borrador de trabajo)
Solicitud y respuesta:
-> { "versión" : "1.1" , "método" : "confirmFruitPurchase" , "params" : [[ "manzana" , "naranja" , "mangos" ], 1.123 ], "id" : "194521489" } <- { "versión" : "1.1" , "resultado" : "hecho" , "error" : nulo , "id" : "194521489" }
Versión 1.0
Solicitud y respuesta:
-> { "método" : "echo" , "params" : [ "Hola JSON-RPC" ], "id" : 1 } <- { "resultado" : "Hola JSON-RPC" , "error" : nulo , "id" : 1 }
Ver también
Referencias
- ^ "especificación - JSON-RPC - Trac" . Archivado desde el original el 17 de mayo de 2008 . Consultado el 14 de mayo de 2008 .
- ^ "Especificación JSON-RPC 2.0" .
id: un identificador establecido por el cliente que DEBE contener una cadena, un número o un valor NULO si se incluye. Si no está incluido, se supone que es una notificación. El valor normalmente NO DEBE ser Nulo y los Números NO DEBEN contener partes fraccionarias
- ^ "Especificación JSON-RPC 2.0" .
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 es necesario 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, ya que no tienen un objeto Respuesta para ser devuelto. Como tal, el Cliente no se daría cuenta de ningún error (como por ejemplo, "Parámetros no válidos", "Error interno").
- ^ "Especificación JSON-RPC 2.0" .
resultado: este miembro es OBLIGATORIO en caso de éxito. Este miembro NO DEBE existir si hubo un error al invocar el método. El valor de este miembro está determinado por el método invocado en el servidor.
- ^ "Especificación JSON-RPC 2.0" .
error: este miembro es REQUERIDO en caso de error. Este miembro NO DEBE existir si no se activó ningún error durante la invocación. El valor de este miembro DEBE ser un Objeto como se define en la sección 5.1.
- ^ "Especificación JSON-RPC 2.0" .
Objeto de error: cuando una llamada rpc encuentra un error, el objeto de respuesta DEBE contener el miembro de error con un valor que es un objeto con los siguientes miembros: (código) - Un número que indica el tipo de error que ocurrió. DEBE ser un número entero. (mensaje): una cadena que proporciona una breve descripción del error. El mensaje DEBE limitarse a una sola oración concisa. (datos): un valor primitivo o estructurado que contiene información adicional sobre el error. Esto puede omitirse. El valor de este miembro lo define el servidor (por ejemplo, información de error detallada, errores anidados, etc.).
enlaces externos
- Página web oficial
- JSON-RPC Google Group discutiendo temas relacionados con el protocolo
- Especificaciones JSON-RPC, MNlinks, etc.
- Descripción de transporte HTTP para JSON-RPC-2
- Formato de descripción del servicio de especificación OpenRPC para JSON-RPC. (open-api, pero para json rpc)