兼容性:
JSON-RPC 2.0 的请求对象和响应对象可能无法在现用的JSON-RPC 1.0 客户端或服务端工作,然而我们可以很容易在两个版本间区分出2.0,总会包含一个成员命名为 “jsonrpc” 且值为“2.0”, 而1.0版本是不包含的。大部分的2.0实现应该考虑尝试处理1.0的对象,即使不是对等的也应给其相关提示
注意:
- 在请求对象中不建议使用NULL作为id值,因为该规范将使用空值认定为未知id的请求。另外,由于JSON-RPC 1.0 的通知使用了空值,这可能引起处理上的混淆。
- 使用小数是不确定性的,因为许多十进制小数不能精准的表达为二进制小数
请求对象
发送一个请求对象至服务端代表一个rpc调用, 一个请求对象包含下列成员:
jsonrpc
指定JSON-RPC协议版本的字符串,必须准确写为“2.0”
method
包含所要调用方法名称的字符串,以rpc开头的方法名,用英文句号(U+002E or ASCII 46)连接的为预留给rpc内部的方法名及扩展名,且不能在其他地方使用。
params
调用方法所需要的结构化参数值,该成员参数可以被省略。
id
已建立客户端的唯一标识id,值必须包含一个字符串、数值或NULL空值。如果不包含该成员则被认定为是一个通知。该值一般不为NULL(在请求对象中不建议使用NULL作为id值,因为该规范将使用空值认定为未知id的请求。另外,由于JSON-RPC 1.0 的通知使用了空值,这可能引起处理上的混淆。),若为数值则不应该包含小数(使用小数是不确定性的,因为许多十进制小数不能精准的表达为二进制小数)。
响应对象
jsonrpc
指定JSON-RPC协议版本的字符串,必须准确写为“2.0”
result
该成员在成功时必须包含。
当调用方法引起错误时必须不包含该成员。
服务端中的被调用方法决定了该成员的值。
error
该成员在失败是必须包含。
当没有引起错误的时必须不包含该成员。
该成员参数值必须为5.1中定义的对象。
id
该成员必须包含。
该成员值必须于请求对象中的id成员值一致。
若在检查请求对象id时错误(例如参数错误或无效请求),则该值必须为空值。
错误代码
当一个rpc调用遇到错误时,返回的响应对象必须包含错误成员参数,并且为带有下列成员参数的对象:
code
使用数值表示该异常的错误类型。 必须为整数。
message
对该错误的简单描述字符串。 该描述应尽量限定在简短的一句话。
data
包含关于错误附加信息的基本类型或结构化类型。该成员可忽略。 该成员值由服务端定义(例如详细的错误信息,嵌套的错误等)
网友评论