JSON-RPC

JSON-RPC は、エンコード（符号化）にJSONを採用した遠隔手続き呼出し (RPC) プロトコルの一種である。 非常にシンプルなプロトコルであり、少数のデータ型やコマンドのみが定義されている。JSON-RPCでは、通知（データをサーバに送信するもののレスポンスを必要としない）と、順序の保証されない複数呼び出しが可能である。

類似のプロトコルとしてはエンコードにXMLを用いるXML-RPCが存在する。

歴史

バージョン 説明 日時
1.0 初版 2005
1.1 WD ワーキングドラフト、名前付きパラメータやエラーコードの追加 2006-08-07
1.1 Alt シンプルなJSON-RPC 1.1のための提案、1.1 WDの代替案 2007-05-06
1.1 Object Specification オブジェクト仕様、1.1 WD/1.1ALTの代替案 2007-07-30
1.2 提案、後に2.0となる 2007-12-27
2.0 仕様提案 2009-05-24
2.0 (Revised-) 仕様 2010-03-26

使い方

JSON-RPCはこのプロトコルを実装するサーバに送信されることで用いられる。クライアントは一般的にはリモートシステムのメソッドを呼び出すことを意図したソフトウェアとなる。複数の入力パラメータを配列やオブジェクトとしてリモートメソッドに送信することが出来るが、またリモートメソッドも複数の出力データを返すことができる（この動作はバージョンにより異なる）。

全ての転送データはシリアライズされたJSONオブジェクトとしてあらわされる[1]。リクエストはリモートシステムが提供する特定のメソッドを呼び出す。リクエストには以下の3つの重要なプロパティを含む必要がある。

  • method - 実行するメソッド名の文字列。
  • params - メソッドに渡されるパラメータのオブジェクトまたは配列。
  • id - リクエストに対応するレスポンスを識別するための文字列または数値。

リクエストを受け取った側は、受け取った全てのリクエストに対して正しいレスポンスを返さなければならない。レスポンスは正常/エラーに応じて以下のプロパティを含む必要がある。

  • result - 正常に実行された場合、メソッドを実行した結果。
  • error - エラーが発生した場合、その内容を示すオブジェクト。
  • id - リクエストで渡されたid。

この他に、レスポンスを必要としない通知のための仕組みが導入されている。レスポンスを返さない場合idは必要ないため、通知のリクエストはidを取り除いたリクエストの形式になっている。通知の場合 id を送らない（バージョン2.0）または null にする（バージョン1.0）べきである。

例

以下のサンプルでは、サーバへのリクエストを --> で、サーバからのレスポンスを <-- で示す（ただしレスポンスはJSON-RPCのバージョンによっては必須ではない）。

バージョン2.0

リクエストとレスポンス
--> {"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3}
<-- {"jsonrpc": "2.0", "result": 19, "id": 3}
通知（リクエストのみ）
--> {"jsonrpc": "2.0", "method": "update", "params": [1,2,3,4,5]}

バージョン1.1（ワーキングドラフト）

リクエストとレスポンス
--> {"version": "1.1", "method": "confirmFruitPurchase", "params": [["apple", "orange", "mangoes"], 1.123], "id": "194521489"}
<-- {"version": "1.1", "result": "done", "error": null, "id": "194521489"}

バージョン1.0

リクエストとレスポンス
--> {"method": "echo", "params": ["Hello JSON-RPC"], "id": 1}
<-- {"result": "Hello JSON-RPC", "error": null, "id": 1}

脚注

  1. ^ JSON-RPC 2.0 Specification

関連項目

外部リンク