JSON-RPC は、エンコードにJSONを採用した遠隔手続き呼出し プロトコルの一種で、多くのユーザーにも利用されています。それでは、JSON-RPC APIをテストするために、リクエストを送信したりする必要がある場合は、どうしたらいいですか？本文では、JSON-RPC APIリクエストを送信してレスポンスを検証する方法を皆さんに紹介します。
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のリクエストを送信する方法を皆さんに紹介します。
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データフォーマットを選択するだけで良いのです。非常に便利なので、ぜひ試してください。
PostmanでJSON-RPCのリクエストを送信
それでは、PostmanでJSON-RPCのリクエストを送信する方法を紹介します。
ステップ⒈Postmanを開き、HTTPリクエストを新規に作成します。
ステップ⒉設定の画面で、HTTPメソッドをPOSTに変更します。
ステップ⒊JSON-RPCのエンドポイントURLを入力します。
ステップ⒋Bodyの中で、raw - JSONを選択して、次のJSONフォーマットのデータを入力します。
ステップ⒌「Send」ボタンをクリックしてリクエストを送信します。成功に送信すると、レスポンスのパネルでJSONフォーマットの戻りデータが見られます。
この例では、echoというメソッドを呼び出して、1つのオブジェクトをパラメータにしていました。リクエストの唯一の識別子は123になっています。
