JSON-RPC 2.0

JSON-RPC 2.0 仕様

発行日:

2010年3月26日 (2009年5月24日版に基づく)

更新日:

2013年1月4日

著者:

JSON-RPC ワーキンググループ <json-rpc@googlegroups.com>

1 概要

JSON-RPC はシンプルに設計されています。

2 規約

本文書におけるキーワード「MUST（しなければならない）」、「MUST NOT（してはならない）」、「REQUIRED（必須）」、「SHALL（するべき）」、「SHALL NOT（するべきではない）」、「SHOULD（すべきである）」、「SHOULD NOT（すべきではない）」、「RECOMMENDED（推奨される）」、「MAY（してもよい）」、「OPTIONAL（選択できる）」は、RFC 2119 の記述に従って解釈されます。

クライアントとサーバー間で交換される、あらゆる種類のマッチング対象となるすべてのメンバー名は、大文字と小文字を区別するものとします。関数、メソッド、およびプロシージャという用語は互換性があると想定されます。

クライアントは、リクエストオブジェクトの生成元であり、レスポンスオブジェクトのハンドラーとして定義されます。

サーバーは、レスポンスオブジェクトの生成元であり、リクエストオブジェクトのハンドラーとして定義されます。

この仕様の1つの実装は、他の異なるクライアントまたは同じクライアントに対して、これらの両方の役割を同時に容易に果たすことができます。この仕様では、その複雑な層については扱いません。

3 互換性

JSON-RPC 2.0 のリクエストオブジェクトとレスポンスオブジェクトは、既存の JSON-RPC 1.0 クライアントまたはサーバーでは動作しない可能性があります。ただし、2.0 には常に「jsonrpc」という名前のメンバーがあり、その文字列値は「2.0」であるのに対し、1.0 にはそれがないため、2 つのバージョンを簡単に区別できます。ほとんどの 2.0 実装では、1.0 のピアツーピア機能やクラスヒント機能は利用できないとしても、1.0 オブジェクトの処理を検討する必要があります。

4 リクエストオブジェクト

RPC呼び出しは、リクエストオブジェクトをサーバーに送信することで表現されます。リクエストオブジェクトは以下のメンバーを持ちます。

jsonrpc

JSON-RPCプロトコルのバージョンを指定する文字列。必ず「2.0」でなければなりません。

method

呼び出されるメソッド名を含む文字列。rpcという単語で始まり、その後にピリオド文字（U+002EまたはASCII 46）が続くメソッド名は、RPC内部メソッドおよび拡張用に予約されており、他の用途に使用してはなりません。

params

メソッドの呼び出し時に使用されるパラメータ値を保持する構造化値。このメンバーは省略可能です。

id

サーバーは、レスポンスオブジェクトに小数部が含まれている場合、同じ値で応答しなければなりません（MUST）。このメンバーは、2つのオブジェクト間のコンテキストを関連付けるために使用されます。

4.1 通知

通知は、「id」メンバーを持たないリクエストオブジェクトです。通知であるリクエストオブジェクトは、クライアントが対応するレスポンスオブジェクトを必要としないことを示すため、クライアントにレスポンスオブジェクトを返す必要はありません。サーバーは、バッチリクエスト内の通知を含め、通知に応答してはなりません（MUST NOT）。

通知は、返されるレスポンスオブジェクトを持たないため、定義上確認できません。そのため、クライアントはエラー（「無効なパラメータ」、「内部エラー」など）に気付くことはありません。

4.2 パラメータ構造

RPC呼び出しのパラメータが存在する場合、構造化された値として提供する必要があります。配列を介した位置指定、またはオブジェクトを介した名前指定のいずれかです。

位置指定: パラメータは、サーバーが想定する順序で値を含む配列である必要があります。

名前指定: パラメータは、サーバーが想定するパラメータ名と一致するメンバー名を持つオブジェクトである必要があります。想定される名前が指定されていない場合、エラーが発生する可能性があります。名前は、大文字と小文字の区別を含め、メソッドの想定されるパラメータと完全に一致する必要があります。

5 レスポンスオブジェクト

rpc 呼び出しが行われた場合、サーバーは通知の場合を除き、レスポンスで応答しなければなりません（MUST）。レスポンスは単一の JSON オブジェクトで表現され、以下のメンバーを持ちます。

jsonrpc

JSON-RPC プロトコルのバージョンを指定する文字列。正確に「2.0」でなければなりません。

result

このメンバーは成功時に必須です。

メソッドの呼び出しでエラーが発生した場合、このメンバーは存在してはなりません。

このメンバーの値は、サーバーで呼び出されたメソッドによって決定されます。

error

このメンバーはエラー時に必須です。

呼び出し中にエラーが発生しなかった場合、このメンバーは存在してはなりません。

このメンバーの値は、セクション 5.1 で定義されているオブジェクトでなければなりません（MUST）。

id

このメンバーは必須です。

リクエストオブジェクトの id メンバーの値と同じでなければなりません（MUST）。

リクエストオブジェクト内の ID の検出にエラーが発生した場合（例：解析エラー/無効なリクエスト）、ID は Null である必要があります。

resultメンバーまたはerrorメンバーのいずれかを含める必要がありますが、両方を含めることはできません。

5.1 エラーオブジェクト

RPC 呼び出しでエラーが発生した場合、レスポンスオブジェクトには error メンバーが格納され、その値は以下のメンバーを持つオブジェクトである必要があります。

code

発生したエラーの種類を示す数値。

これは整数である必要があります。

message

エラーの簡単な説明を示す文字列。

message は簡潔な一文に限定する必要があります。

data

エラーに関する追加情報を含むプリミティブ型または構造化型の値。

これは省略可能です。

このメンバーの値はサーバーによって定義されます (例: 詳細なエラー情報、ネストされたエラーなど)。

table:error

code message 意味

-32700 Parse error サーバーが無効なJSONを受信しました。

JSONテキストの解析中にサーバーでエラーが発生しました。

-32600 Invalid Request 送信された JSON は有効なリクエスト オブジェクトではありません。

-32601 Method not found メソッドは存在しない/利用できません。

-32602 Invalit params 無効なメソッドパラメータです。

-32603 Internal Error 内部 JSON-RPC エラー。

-32000 to -32099 Server error 実装定義のサーバー エラー用に予約されています。

残りのスペースは、アプリケーション定義のエラーに使用できます。

6 バッチ

複数のリクエストオブジェクトを同時に送信する場合、クライアントはリクエストオブジェクトを格納した配列を送信できます。

サーバーは、バッチリクエストオブジェクトがすべて処理された後、対応するレスポンスオブジェクトを含む配列で応答する必要があります。レスポンスオブジェクトはリクエストオブジェクトごとに存在する必要があります（SHOULD）。ただし、通知用のレスポンスオブジェクトは存在すべきではありません。サーバーは、バッチ RPC 呼び出しを一連の同時タスクとして処理し、任意の順序と並列処理幅で処理できます（MAY）。

バッチ呼び出しから返されるレスポンスオブジェクトは、配列内で任意の順序で返される場合があります。クライアントは、各オブジェクト内の id メンバーに基づいて、リクエストオブジェクトのセットと結果のレスポンスオブジェクトのセットのコンテキストを一致させる必要があります（SHOULD）。

バッチ RPC 呼び出し自体が有効な JSON として、または少なくとも 1 つの値を持つ配列として認識されなかった場合、サーバーからの応答は単一のレスポンスオブジェクトでなければなりません（MUST）。クライアントに送信される Response 配列内に Response オブジェクトが含まれていない場合、サーバーは空の配列を返してはならず、何も返してはなりません。

7 例

code:構文:

--> data を Server に送る

<-- data を Client に送る

code:位置パラメータ付きrpc呼び出し rpc call with positional parameters:

<-- {"jsonrpc": "2.0", "result": 19, "id": 1}

<-- {"jsonrpc": "2.0", "result": -19, "id": 2}

code:名前付きパラメータ付きrpc呼び出し rpc call with named parameters:

--> {"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}

code:通知 a Notification:

--> {"jsonrpc": "2.0", "method": "foobar"}

code:存在しないメソッドのrpc呼び出し rpc call of non-existent method:

--> {"jsonrpc": "2.0", "method": "foobar", "id": "1"}

<-- {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not found"}, "id": "1"}

code:不正なJSONでrpc呼び出し rpc call with invalid JSON:

--> {"jsonrpc": "2.0", "method": "foobar, "params": "bar", "baz]

<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

code:不正なリクエストobjectでrpc呼び出し rpc call with invalid Request object:

--> {"jsonrpc": "2.0", "method": 1, "params": "bar"}

<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

code:不正なJSONでrpc呼び出しバッチ rpc call Batch, invalid JSON:

--> [

{"jsonrpc": "2.0", "method"

]

<-- {"jsonrpc": "2.0", "error": {"code": -32700, "message": "Parse error"}, "id": null}

code:空配列でrpc呼び出し rpc call with an empty Array:

--> []

<-- {"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

code:不正なバッチ(空ではない)でrpc呼び出し rpc call with an invalid Batch (but not empty):

<-- [

{"jsonrpc": "2.0", "error": {"code": -32600, "message": "Invalid Request"}, "id": null}

]

code:不正なバッチでrpc呼び出し rpc call with invalid Batch:

<-- [

{"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}

]

code:バッチrpc呼び出し rpc call Batch:

--> [

{"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"},

]

code:rpc呼び出しバッチ (全て通知) rpc call Batch (all notifications):

--> [

]

<-- //すべての通知バッチに対して何も返されません

8 拡張

rpc. で始まるメソッド名はシステム拡張用に予約されており、他の用途に使用してはなりません（MUST NOT）。各システム拡張は関連する仕様で定義されています。すべてのシステム拡張はオプションです（OPTIONAL）。

Copyright (C) 2007-2010 by the JSON-RPC Working Group

本文書およびその翻訳は、JSON-RPCの実装に使用でき、複製および他者に提供できます。また、本文書についてコメント、説明、または実装を支援する派生著作物は、上記の著作権表示および本項をすべての複製および派生著作物に含めることを条件として、全体または一部を問わず、いかなる種類の制限もなく作成、複製、公開、配布できます。ただし、本文書自体はいかなる形でも改変できません。

上記で付与された限定的な権限は永続的であり、取り消されることはありません。

この文書およびここに含まれる情報は「現状のまま」提供され、明示的または黙示的を問わず、ここに含まれる情報の使用がいかなる権利も侵害しないという保証、または商品性または特定目的への適合性に関する黙示的保証を含み、これに限定されない、すべての保証は否認されます。