基于 HTTP 的 JSON-RPC

https://www.jsonrpc.org/historical/json-rpc-over-http.htmlhttps://www.jsonrpc.org/historical/json-rpc-over-http.html

日期：	2008-1-15
网站：	http://groups.google.com/group/json-rpc
作者：	Jeffrey Damick 和 JSON-RPC 组 - json-rpc -AT- googlegroups DOT com

内容

• 1 前言
• 2 变更日志
• 3 规格
  • 3.1 概述
  • 3.2 约定
  • 3.3 HTTP头
  • 3.4 发布
  • 3.5 获取
    • 3.5.1 编码参数
  • 3.6 响应代码
    • 3.6.1 成功
    • 3.6.2 错误

---

1 前言

“JSON-RPC 是一种轻量级的远程过程调用协议。它的设计很简单！” [JSON-RPC 1.0]

本文档的目标是提出一个JSON-RPC 1.2扩展来指定

对于邮件列表位置：JSON-RPC Google Group

2 变更日志

• 2008 年 1 月 15 日 - 初始创建

3 规格

3.1 概述

JSON-RPC over HTTP是JSON-RPC 1.2规范的扩展。

3.2 约定

本文档中的关键词“必须”、“不得”、“要求”、“应”、“不应”、“应该”、“不应”、“推荐”、“可以”和“可选”是按照RFC 2119中的描述进行解释。

由于 JSON-RPC 使用 JSON，它与 JSON 共享相同的类型系统（参见http://www.json.org或RFC 4627）。每当本文档引用任何 JSON 类型时，第一个字母总是大写：Object、Array、String、Number、True、False、Null。

客户端是 Request 对象的来源。服务器是响应对象的来源。

3.3 HTTP头

要求：

无论远程过程调用是使用 HTTP GET 还是 POST，HTTP 请求消息必须指定以下标头：

• Content-Type 应该是 'application/json-rpc' 但可能是 'application/json' 或 'application/jsonrequest'
• 必须根据HTTP规范第 4.4 节“消息长度”中规定的指南和规则指定和正确的 Content-Length。
• 必须指定 Accept 并且应该读取 'application/json-rpc' 但可能是 'application/json' 或 'application/jsonrequest'。

3.4 POST

帖子正文包含JSON-RPC 1.2 第 2.4 节中指定的对象请求。

对 Post 的响应包含JSON-RPC 1.2 第 2.5 节中指定的对象响应。

带有空错误的响应将产生 HTTP 200 状态代码，而非空错误代码将映射到错误部分中指定的 HTTP 状态代码。

--> POST /ENDPOINT HTTP/1.1
 Host: ...
 Content-Type: application/json-rpc
 Content-Length: ...

 {"method": "sum", "params": {"a":3, "b":4}, "id":0}

<-- HTTP/1.1 200 OK
 ...
 Content-Type: application/json-rpc

 {"result": 7, "error": null, "id": 0}


--> POST /ENDPOINT HTTP/1.1
 Host: ...
 Content-Type: application/json-rpc
 Content-Length: ...

 {"method": "test", "params": [], "id": 0}

3.5 GET

• 必须是数组或对象参数[1]
• 请记住，一些旧客户端和代理存在 URI 长度超过 255 个字节的问题[2]
• HTTP POST 是发送 JSON-RPC 的首选方法
• 参数必须编码

http://<end point>?method=<method name>&params=<encoded params>&id=1

3.5.1 编码参数

编码步骤：

1. Base 64参数值
2. URL 编码的Base 64 参数值

预编码参数：

http://<end point>?method=sum&params={"a":3,"b":4}&id=2
http://<end point>?method=sum&params=[3,4]&id=1

编码请求：

http://<end point>?method=sum&params=eyJhIjozLCJiIjo0fQ%3D%3D&id=2
http://<end point>?method=sum&params=WzMsNF0%3D&id=1

3.6 响应代码

3.6.1 成功

对于非通知请求[3]，包括使用POST或GET的系统过程，必须使用HTTP状态代码：200指示成功响应。

但是，对于JSON-RPC 1.2 通知请求，成功响应必须是HTTP状态代码：204。

3.6.2 错误

HTTP 状态	代码	信息
500	-32700	解析错误。
400	-32600	非法请求。
404	-32601	找不到方法。
500	-32602	参数无效。
500	-32603	内部错误。
500	-32099..-32000	服务器错误。

有关错误代码的更多详细信息，请参阅JSON-RPC 1.2 第 2.5.1 节中的表格。

有关 HTTP 状态代码的更多详细信息，请参阅HTTP部分 6.1.1。

---

[1]	根据JSON-RPC 1.2规范

[2]	aspfaq.com

[3]	JSON-RPC 1.2 第 2.4 节

---

JSON-RPC 工作组版权所有 (C) 2008

本文档及其翻译可用于通过 HTTP 实现 JSON-RPC，可复制并提供给其他人，并且可以准备、复制、发布和分发对其进行评论或以其他方式解释或协助其实施的衍生作品，全部或部分，不受任何形式的限制，前提是上述版权声明和本段包含在所有此类副本和衍生作品中。但是，不得以任何方式修改本文档本身。

上述授予的有限权限是永久的，不会被撤销。

本文档和此处包含的信息按“原样”提供，不提供任何明示或暗示的保证，包括但不限于使用此处信息不会侵犯任何权利或适销性或适用性的任何暗示保证出于特定目的。