REST ゲートウェイ

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

HTTP リクエスト

REST ゲートウェイはポート 3000 番を使用します。HTTP GETPUT そして POST リクエストを受け付けます。

Catapult REST がローカルで動いているのであれば、HTTP GET リクエストはブラウザからこのように実行できます:

http://localhost:3000/<path-to-API-request>

HTTP PUT と POST リクエストは同じ構造ですが、リクエストボディに JSON 形式を使用します。この種のリクエストは、それが可能なプラグインを利用しないことにはブラウザから実行することができません。

Endpoints

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

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

レスポンスコード

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

  • 2xx 番台コードは成功を示します。
  • 4xx 番台コードはユーザーが提供した情報でエラーが発生したことを示します。
  • 5xx 番台のコードはノードのエラーを示します。
HTTP ステータスコード概要
エラーコード レスポンス 説明
200 OK すべて想定通りに稼働している
202 Accepted リクエストは受理されましたが、処理は完了していません。
400 InvalidContent 提供された引数は、許容できるタイプの入力ではありませんでした
404 ResourceNotFound リクエストしたリソースは存在しません。
409 InvalidArgument リクエストに必要な引数が欠落しているか、受け入れられませんでした
500 InternalServiceError REST ゲートウェイでエラーが発生しました
503 ServiceUnavailable API ノードまたはデータベースサービスのいずれかが REST ゲートウェイから使用できないか、到達できません

WebSockets

ブロックチェーン上でのイベントの発生による リアルタイムな更新 を得るために、 Catapult REST は WebSocket を公開しています。クライアントアプリケーションは WebSocket 接続を開くと一意な識別子を得られます。この識別子によって、アプリケーションは更新のために API を絶えずポーリングするのではなく、使用可能なチャンネルを購読する資格を得ます。チャンネルでイベントが発生すると REST ゲートウェイは購読しているすべてのクライアントにリアルタイムで通知を送信します。

WebSocket URI は HTTP リクエスト URI と同じホストとポートを共有しますが ws:// プロトコルを使用します:

ws://localhost:3000/ws

Response format

すべてのチャンネルは同じレスポンスフォーマットを共有しています:

{
    "topic": "{subscribed-channel}",
    "data": {}
}
  • topic には購読しているチャンネル名が含まれているため、同じ WebSocket を使用して複数のチャンネルを監視できます (topic は購読時にリクエストボディで提供される subscribe フィールドに一致します)
  • data はチャンネル固有のオブジェクトです。以下にリストされている各チャンネルは、それが返すデータオブジェクトについて説明しています。

チャンネル

ブロック

block チャンネルは、新しいブロックが取得されるたび、購読しているクライアントへ通知します。返却される各メッセージには、収集されたブロックに関する情報が含まれます。

リクエストボディ

{
    "uid": "{uid}",
    "subscribe": "block"
}

Response data

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

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

リクエストボディ

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

Response data

confirmedAdded/{address}

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

リクエストボディ

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

Response data

unconfirmedAdded/{address}

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

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

リクエストボディ

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

Response data

unconfirmedRemoved/{address}

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

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

リクエストボディ

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

Response data

  • Hash

partialAdded/{address}

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

リクエストボディ

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

Response data

partialRemoved/{address}

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

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

リクエストボディ

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

Response data

  • Hash

cosignature/{address}

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

リクエストボディ

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

Response data

status/{address}

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

リクエストボディ

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

Response data