REST ゲートウェイ

Catapult REST は HTTP と WebSockets をブロックチェーン上で読み書きアクションが実行できるように併合します。

HTTP リクエスト

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.

Endpoints

次のドキュメントを参照して、使用可能なエンドポイントのリストを確認できます。

API 仕様と REST ゲートウェイ実装との互換性を確認するには製品互換性表を参照してください。

レスポンスコード

Symbol は従来の HTTP レスポンスコードを使用して、API リクエストの成功または失敗を示します。

2xx 番台コードは成功を示します。
4xx 番台コードはユーザーが提供した情報でエラーが発生したことを示します。
5xx 番台のコードはノードのエラーを示します。

HTTP ステータスコード概要
エラーコード	レスポンス	説明
`200`	OK	すべて想定通りに稼働している
`202`	Accepted	リクエストは受理されましたが、処理は完了していません。
`400`	InvalidContent	The provided argument was not an acceptable input.
`404`	ResourceNotFound	リクエストしたリソースは存在しません。
`409`	InvalidArgument	リクエストに必要な引数が欠落しているか、受け入れられませんでした
`500`	InternalServiceError	REST ゲートウェイでエラーが発生しました
`503`	ServiceUnavailable	Either API node or database service is unavailable or unreachable from the REST Gateway. Check the `/node/health` endpoint.

ページネーション

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.

ページング可能な各エンドポイントは、独自のフィルターセットを定義しています。次の表はすべての検索可能なエンドポイントに存在するクエリパラメータを示しています:

クエリパラメータ	タイプ	説明	デフォルト
`pageSize`	integer `[10..100]`	返却するエントリの数を選択します。例: `http://localhost:3000/blocks?pageSize=100` `ページ` あたり 100 エントリを返却します	`10`
`pageNumber`	integer `>=1`	ページ番号でフィルタします。例: `http://localhost:3000/blocks?page=2` 2 ページ目を返却します。	`1`
`offset`	string (id)	ページネーションを開始するエントリを識別します。例: `http://localhost:3000/blocks?id=EE94FD819A1B30D6C5D1C03`
`order`	string `{asc, desc}`	Sorts the responses in ascending or descending order based on the collection property set on the parameter `orderBy`. If the request does not specify `orderBy`, REST returns the collection ordered by id. Example: `http://localhost:3000/blocks?order=asc` returns the block entries in ascending order.	`desc`
`orderBy`	string	ソートするパラメーターを選択します。デフォルトでは、すべてのコレクションは ID でソート可能ですが、コレクションは追加プロパティを定義可能です。

複数のクエリパラメータを同じ呼び出しで組み合わせることができます。例: http://localhost:3000/blocks?pageSize=100&id=EE94FD819A1B30D6C5D1C03 will ブロック ID EE94FD819A1B30D6C5D1C03 を起点に、ページごと 100 ブロックエントリを返却します。

レスポンスにはページネーションのエントリの総数、現在のページ番号、およびページ総数などのメタ情報も含まれます。これはページネーションのレスポンスメタ情報の例です:

{
  "data": [
    {}
  ],
  "pagination": {
    "pageNumber": 0,
    "pageSize": 0,
    "totalEntries": 0,
    "totalPages": 0
  }
}

WebSockets

ブロックチェーン上でのイベントの発生による リアルタイムな更新 を得るために、 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"
}

レスポンスデータ

BlockInfoDTO

ファイナライズ済みブロック

finalizedBlock チャンネルは、ブロックの集合が finalized されるたびに購読しているクライアントに通知します。返却される各メッセージには、ファイナライズラウンドの 最も高いブロック に関する情報が含まれています。高さが低いブロックはすべてファイナライズ済みと見なされます。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "finalizedBlock"
}

レスポンスデータ

FinalizedBlockDTO

confirmedAdded/{address}

confirmedAdded チャンネルは、指定されたアドレスに関連するトランザクションがブロックに含まれると、購読しているクライアントに通知します。返却される各メッセージには、承認されたトランザクションに関する情報が含まれます。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "confirmedAdded/{address}"
}

レスポンスデータ

TransactionInfoDTO

unconfirmedAdded/{address}

unconfirmedAdded チャンネルは、指定されたアドレスに関連するトランザクションが未承認の状態になり、ブロックに含まれるのを待機しているときに、購読しているクライアントに通知します。返却される各メッセージには、未承認のトランザクションに関する情報が含まれます。

トランザクションが PUT /transaction HTTP エンドポイントによりアナウンスされるか、 AggregateBondedTransaction のすべての署名が揃い、partial から未承認へ変わるとき、このメッセージが届く可能性があります。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "unconfirmedAdded/{address}"
}

レスポンスデータ

TransactionInfoDTO

unconfirmedRemoved/{address}

unconfirmedRemoved チャンネルは、指定されたアドレスに関連するトランザクションが未確認の状態を抜けると、購読しているクライアントに通知します。返却される各メッセージには、承認されていないトランザクションハッシュが含まれます。

このメッセージが受信された場合に考えられるシナリオは、トランザクションが確認されたか、期限に達していてトランザクションがブロックに含まれていなかった場合です。

リクエストボディ

{
    "uid":"{uid}",
    "subscribe":"unconfirmedRemoved/{address}"
}

レスポンスデータ

Hash

partialAdded/{address}

partialAdded チャンネルは、指定されたアドレスに関連する AggregateBondedTransaction が部分的な状態になり、必要なすべての署名が完了するのを待っているときに、購読したクライアントに通知します。返却される各メッセージには、追加された部分トランザクションに関する情報が含まれます。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "partialAdded/{address}"
}

レスポンスデータ

TransactionInfoDTO

partialRemoved/{address}

partialRemoved チャンネルは、指定されたアドレスに関連するトランザクションが部分的な状態を終了すると、購読したクライアントに通知します。返却される各メッセージには、削除された部分的なトランザクションハッシュが含まれます。

このメッセージが出されたときに考えられるシナリオは次のとおりです。必要なすべての署名が受信され、トランザクションが未承認であるか、期限に達し、トランザクションがブロックに含まれていません。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "partialRemoved/{address}"
}

レスポンスデータ

Hash

cosignature/{address}

cosignature チャンネルは、指定されたアドレスに関連する連署者に署名されたトランザクションがパーシャル状態で AggregateBondedTransaction に追加されると、購読したクライアントに通知します。返却される各メッセージには、署名者が署名したトランザクションが含まれます。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "cosignature/{address}"
}

レスポンスデータ

CosignatureDTO

status/{address}

status チャンネルは、指定されたアドレスに関連するトランザクションがエラーを通知したときに、購読したクライアントに通知します。返される各メッセージには、エラーメッセージとトランザクションハッシュが含まれます。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "status/{address}"
}

レスポンスデータ

TransactionStatusDTO

ナビゲーション

REST ゲートウェイ

HTTP リクエスト

Endpoints

レスポンスコード

ページネーション

WebSockets

レスポンス形式

チャンネル