APIテスト APIナレッジベース Locale JP

JSON-RPCとは、JSON-RPC APIリクエストを簡単に送信する

JSON-RPC は、エンコードにJSONを採用した遠隔手続き呼出しプロトコルの一種で、多くのユーザーにも利用されています。それでは、JSON-RPC APIをテストするために、リクエストを送信したりする必要がある場合は、どうしたらいいですか？本文では、JSON-RPC APIリクエストを送信してレスポンスを検証する方法を皆さんに紹介します。

shimizu chioka

Updated on 2024年11月1日 4分読む

JSON-RPCとは

JSON-RPC（JSON Remote Procedure Call）は、RPC（Remote Procedure Call）の一形態であり、JSON（JavaScript Object Notation）を使用してクライアントとサーバー間のリモート手続き呼び出しを行うためのプロトコルです。

JSON-RPCでは、クライアントがJSON形式のリクエストメッセージを作成し、それをサーバーに送信します。サーバーはリクエストを受け取り、適切な処理を行った後、JSON形式のレスポンスメッセージをクライアントに返します。

JSON-RPC 1.0と2.0の違い

現在、多く利用されるのは、JSON-RPC バージョン 2.0になります。それでは、バージョン2.0と1.0との違いは何ですか？この部分では、この点について、皆さんに紹介しようと思います。

バージョン指定

1.0ではバージョン番号の記載は任意でした。
2.0ではリクエストのjsonrpcフィールドに"2.0"と記載することが必須となりました。

エラー形式

1.0ではエラーは単純な文字列を返していました。
2.0ではエラーコードとメッセージからなるエラーオブジェクトが定義され、詳細なエラー処理が可能になりました。

データ形式

1.0ではJSONの他にXMLなども提案されていました。
2.0ではJSONのみを公式なデータ形式として標準化しました。

バッチ呼び出し

1.0にはバッチ呼び出しの仕様はありませんでした。
2.0で配列によるバッチ呼び出しが追加され、効率的な呼び出しが可能になりました。

通知メソッド

1.0には通知専用のメソッドは存在しませんでした。
2.0でnotifyメソッドが追加され、サーバーへの通知がしやすくなりました。

このように2.0ではJSON形式の統一、エラーハンドリングの改善、機能拡張が図られています。

JSON-RPCの特徴

JSON-RPCは、JSONを利用した軽量なRPC(リモートプロシージャコール)の仕様として、特徴は以下の通りです。

JSONをデータフォーマットとして利用する
HTTPなどをトランスポートプロトコルとして利用できる
リクエストとレスポンスの形式が定義されている
メソッド呼び出し方式で、関数のパラメータと返り値を表現できる

リクエストの例は以下のようなJSON形式です。

{ "jsonrpc": "2.0", "method": "subtract", "params": [42, 23], "id": 1}

jsonrpc: バージョンを指定
method: 呼び出すメソッド名
params: メソッドに渡すパラメータ
id: 呼び出しを一意に識別するID

レスポンスは以下のようなJSONになります。

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

result: メソッドの戻り値
id: レスポンスをリクエストに紐付けるID

JSON-RPCは言語に依存しないシンプルな設計のため、様々なシステム間の通信に利用されています。JavaScriptを利用したウェブAPIの実装などでよく使われています。

JSON-RPCのメソッドとステータスコード

JSON-RPCでは、REST APIと同じように、メソッドとスターテスコードがありますが、REST APIには違いがあります。

JSON-RPCのメソッド

まず、JSON-RPCのメインとなるのはリモートプロシージャコールを実現するために、2つのメソッドがあります。

rpc.call - リモートプロシージャを呼び出す
rpc.notify - 通知のための1方向の呼び出し

rpc.callは正常系のリクエスト/レスポンス形式で、関数の呼び出しと結果の返却ができます。rpc.notifyはレスポンスを必要としない1方向の通知メソッドです。

このほか、JSON-RPC 2.0で定義されているメソッドには以下のようなものがあります。

rpc.discover - サポートされるRPCメソッドの一覧を取得
rpc.status - RPCサーバーのステータスやメタ情報を取得
rpc.ping - 生存確認のためのping/pong
rpc.cancel - 遅延しているRPC呼び出しのキャンセル

などです。JSON-RPCを利用する場合、基本的なrpc.callとrpc.notifyに加え、状況に応じてこれらの補助的なメソッドを使い分けることで、柔軟にAPIを設計できます。

JSON-RPCのエラーコード

また、REST APIと同じように、ステータスコードでリクエストの状態を表示しています。ただし、RESTの200、400などと違って、JSON-RPCは、専属のステータスコードがあります。また、JSON-RPCの場合、レスポンスに成功した場合、HTTP 200 OKのようなステータスコードがなくて、エラーが発生する時のエラーコードのみが存在しています。

JSON-RPCとHTTPのエラーコードの対照表は以下のようになります。

JSON-RPCエラーコード	概要	対応するHTTPステータスコード
-32600	Invalid Request	400 Bad Request
-32601	Method not found	404 Not Found
-32602	Invalid params	400 Bad Request
-32603	Internal error	500 Internal Server Error
-32000 to -32099	Server error	500 Internal Server Error

JSON-RPCの-32xxxのエラーは、4xxや5xxの適切なHTTPステータスコードにマッピングするのが一般的。
特に-32600, -32602は入力値のエラーなので400 Bad Requestが適切。
-32601はメソッドが見つからないので404 Not Foundが適切。
-32603や-32xxxはサーバー側のエラーなので500 Internal Server Errorが適切。

この対応表を参考に、JSON-RPCのエラーコードをHTTPのステータスコードに適切にマッピングする実装が重要です。

徹底ガイド：JSON-RPCのリクエストを送信する

JSON-RPCは、REST APIと同じように普及されていないため、それに対応できるリクエストツールもそんなに多くありません。本文では、JSON-RPC リクエストを送信できるツールをまとめ、これらのツールを使って、JSON-RPCのリクエストを送信する方法を皆さんに紹介します。

button

ApidogでJSON-RPCリクエストを1クリックで簡単に送信

Apidogは、非常に強力的なAPI管理ツールとして、JSON-RPCにも互換できます。また、Apidogは、HTTPプロトコルを使用したAPIに全面的に対応し、GraphQL、WebSocket、gRPCなどのプロトコルにも対応できます。そこで、どのようなAPIを設計したり、テストしたりしたい場合でも、Apidogは役立つツールになります。

上記のように、JSON-RPC APIリクエストを送信してレスポンスを検証したり、JSON-RPC APIのテストを行ったりする場合、Apidogで当該APIのBodyタブでJSONデータフォーマットを選択するだけで良いのです。非常に便利なので、ぜひ試してください。

button

PostmanでJSON-RPCのリクエストを送信

それでは、PostmanでJSON-RPCのリクエストを送信する方法を紹介します。

ステップ⒈Postmanを開き、HTTPリクエストを新規に作成します。

ステップ⒉設定の画面で、HTTPメソッドをPOSTに変更します。

ステップ⒊JSON-RPCのエンドポイントURLを入力します。

ステップ⒋Bodyの中で、raw - JSONを選択して、次のJSONフォーマットのデータを入力します。

ステップ⒌「Send」ボタンをクリックしてリクエストを送信します。成功に送信すると、レスポンスのパネルでJSONフォーマットの戻りデータが見られます。

この例では、echoというメソッドを呼び出して、1つのオブジェクトをパラメータにしていました。リクエストの唯一の識別子は123になっています。