Catapult REST は HTTP と WebSockets をブロックチェーン上で読み書きアクションが実行できるように併合します。
The REST Gateway uses port 3000 for HTTP and port 3001 for HTTPS, and it accepts GET, PUT and POST requests.
Assuming that Catapult REST is running locally, HTTP GET requests can be executed from a browser and have the format:
http://localhost:3000/<path-to-API-request>
PUT and POST requests have the same query format but use JSON structures in the request body. This kind of request cannot usually be executed from within the browser unless you use an extension.
次のドキュメントを参照して、使用可能なエンドポイントのリストを確認できます。
API 仕様と REST ゲートウェイ実装との互換性を確認するには 製品互換性表 を参照してください。
Symbol は従来の HTTP レスポンスコードを使用して、API リクエストの成功または失敗を示します。
2xx 番台コードは成功を示します。
4xx 番台コードはユーザーが提供した情報でエラーが発生したことを示します。
5xx 番台のコードはノードのエラーを示します。
When a query returns more than one result, the REST Gateway paginates the responses by default. The query parameters can be customized to advance through the pages and filter the returned content.
ページング可能な各エンドポイントは、独自のフィルターセットを定義しています。次の表はすべての検索可能なエンドポイントに存在するクエリパラメータを示しています:
クエリパラメータ |
タイプ |
説明 |
デフォルト |
|---|---|---|---|
|
integer |
返却するエントリの数を選択します。例: |
|
|
integer |
ページ番号でフィルタします。例: |
|
|
string (id) |
ページネーションを開始するエントリを識別します。例: |
|
|
string |
Sorts the responses in ascending or descending order based on the collection property set on the parameter |
|
|
string |
ソートするパラメーターを選択します。デフォルトでは、すべてのコレクションは ID でソート可能ですが、コレクションは追加プロパティを定義可能です。 |
複数のクエリパラメータを同じ呼び出しで組み合わせることができます。例: http://localhost:3000/blocks?pageSize=100&id=EE94FD819A1B30D6C5D1C03 will ブロック ID EE94FD819A1B30D6C5D1C03 を起点に、ページごと 100 ブロックエントリを返却します。
レスポンスにはページネーションのエントリの総数、現在のページ番号、およびページ総数などのメタ情報も含まれます。これはページネーションのレスポンスメタ情報の例です:
{
"data": [
{}
],
"pagination": {
"pageNumber": 0,
"pageSize": 0,
"totalEntries": 0,
"totalPages": 0
}
}
ブロックチェーン上でのイベントの発生による リアルタイムな更新 を得るために、 Catapult REST は WebSocket を公開しています。クライアントアプリケーションは WebSocket 接続を開くと一意な識別子を得られます。この識別子によって、アプリケーションは更新のために API を絶えずポーリングするのではなく、使用可能なチャンネルを購読する資格を得ます。チャンネルでイベントが発生すると REST ゲートウェイは購読しているすべてのクライアントにリアルタイムで通知を送信します。
WebSocket URI は HTTP リクエスト URI と同じホストとポートを共有しますが ws:// プロトコルを使用します:
ws://localhost:3000/ws
ガイド: WebSocket チャンネルの購読
すべてのチャンネルは同じレスポンスフォーマットを共有しています:
{
"topic": "{subscribed-channel}",
"data": {}
}
topic には購読しているチャンネル名が含まれているため、同じ WebSocket を使用して複数のチャンネルを監視できます (topic は購読時にリクエストボディで提供される subscribe フィールドに一致します)
data はチャンネル固有のオブジェクトです。以下にリストされている各チャンネルは、それが返すデータオブジェクトについて説明しています。
ブロック
block チャンネルは、新しいブロックが取得されるたび、購読しているクライアントへ通知します。返却される各メッセージには、収集されたブロックに関する情報が含まれます。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "block"
}
レスポンスデータ
ファイナライズ済みブロック
finalizedBlock チャンネルは、ブロックの集合が finalized されるたびに購読しているクライアントに通知します。返却される各メッセージには、ファイナライズラウンドの 最も高いブロック に関する情報が含まれています。高さが低いブロックはすべてファイナライズ済みと見なされます。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "finalizedBlock"
}
レスポンスデータ
confirmedAdded/{address}
confirmedAdded チャンネルは、指定されたアドレスに関連するトランザクションがブロックに含まれると、購読しているクライアントに通知します。返却される各メッセージには、承認されたトランザクションに関する情報が含まれます。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "confirmedAdded/{address}"
}
レスポンスデータ
unconfirmedAdded/{address}
unconfirmedAdded チャンネルは、指定されたアドレスに関連するトランザクションが未承認の状態になり、ブロックに含まれるのを待機しているときに、購読しているクライアントに通知します。返却される各メッセージには、未承認のトランザクションに関する情報が含まれます。
トランザクションが PUT /transaction HTTP エンドポイントによりアナウンスされるか、 AggregateBondedTransaction のすべての署名が揃い、partial から未承認へ変わるとき、このメッセージが届く可能性があります。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "unconfirmedAdded/{address}"
}
レスポンスデータ
unconfirmedRemoved/{address}
unconfirmedRemoved チャンネルは、指定されたアドレスに関連するトランザクションが未確認の状態を抜けると、購読しているクライアントに通知します。返却される各メッセージには、承認されていないトランザクションハッシュが含まれます。
このメッセージが受信された場合に考えられるシナリオは、トランザクションが確認されたか、期限に達していてトランザクションがブロックに含まれていなかった場合です。
リクエストボディ
{
"uid":"{uid}",
"subscribe":"unconfirmedRemoved/{address}"
}
レスポンスデータ
Hash
partialAdded/{address}
partialAdded チャンネルは、指定されたアドレスに関連する AggregateBondedTransaction が部分的な状態になり、必要なすべての署名が完了するのを待っているときに、購読したクライアントに通知します。返却される各メッセージには、追加された部分トランザクションに関する情報が含まれます。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "partialAdded/{address}"
}
レスポンスデータ
partialRemoved/{address}
partialRemoved チャンネルは、指定されたアドレスに関連するトランザクションが部分的な状態を終了すると、購読したクライアントに通知します。返却される各メッセージには、削除された部分的なトランザクションハッシュが含まれます。
このメッセージが出されたときに考えられるシナリオは次のとおりです。必要なすべての署名が受信され、トランザクションが未承認であるか、期限に達し、トランザクションがブロックに含まれていません。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "partialRemoved/{address}"
}
レスポンスデータ
Hash
cosignature/{address}
cosignature チャンネルは、指定されたアドレスに関連する連署者に署名されたトランザクションがパーシャル状態で AggregateBondedTransaction に追加されると、購読したクライアントに通知します。返却される各メッセージには、署名者が署名したトランザクションが含まれます。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "cosignature/{address}"
}
レスポンスデータ
status/{address}
status チャンネルは、指定されたアドレスに関連するトランザクションがエラーを通知したときに、購読したクライアントに通知します。返される各メッセージには、エラーメッセージとトランザクションハッシュが含まれます。
リクエストボディ
{
"uid": "{uid}",
"subscribe": "status/{address}"
}
レスポンスデータ
Last updated by 
