メッセージ形式

リクエスト

リクエストのメッセージの基本的な形式は以下の通りです。

{
  "id"      : "<メッセージの識別子>",
  "type"    : "<メッセージの種類>",
  "replyTo" : "<レスポンスの受信者へのパス>",
  "dataset" : "<対象データセット名>",
  "body"    : <メッセージ本文>
}

id

概要
そのメッセージの一意な識別子。
値
識別子となる文字列。一意でさえあれば、どんな形式のどんな文字列でも指定できます。値は対応するレスポンスの‘inReplyTo`に使われます。
省略時の既定値
なし。この情報は省略できません。

type

概要
そのメッセージの種類。
値
コマンドの名前の文字列
省略時の既定値
なし。この情報は省略できません。

replyTo

概要
レスポンスの受信者へのパス。
値
<ホスト>:<ポート番号>/<タグ名> で示されたパス文字列。例：localhost:24224/output.
省略時の既定値
なし。この情報は省略可能で、省略した場合はレスポンスのメッセージは単に捨てられます。

dataset

概要
対象となるデータセット。
値
データセット名の文字列。
省略時の既定値
なし。この情報は省略できません。

body

概要
メッセージの本文。
値
オブジェクト、文字列、数値、真偽値、または null。
省略時の既定値
なし。この情報は省略可能です。

レスポンス

レスポンスのメッセージの基本的な形式は以下の通りです。

{
  "type"       : "<メッセージの種類>",
  "inReplyTo"  : "<対応するリクエストメッセージの識別子>",
  "statusCode" : <ステータスコード>,
  "body"       : <メッセージの本文>,
  "errors"     : <ノードから返されたエラー>
}

type

概要
そのメッセージの種類。
値
メッセージの種類を示す文字列。多くの場合は、元のリクエストメッセージの type の値に .result という接尾辞を伴った文字列です。

inReplyTo

概要
対応するリクエストメッセージの識別子。
値
対応するリクエストメッセージの識別子の文字列 related request message.

statusCode

概要
そのメッセージの種類。
値
ステータスコードを示す整数。

レスポンスのステータスコードはHTTPのステータスコードに似ています。

200 およびその他の 2xx のステータス
コマンドが正常に処理されたことを示します。

body

概要
そのリクエストメッセージの処理結果の情報。
値
オブジェクト、文字列、数値、真偽値、または null。

errors

概要
各ノードから返されたすべてのエラー。
値
オブジェクト。

この情報は、コマンドが複数のボリュームに分散して処理された時にのみ現れます。それ以外の場合、レスポンスメッセージは errors フィールドを含みません。詳細はエラーレスポンスの説明を参照して下さい。

エラーレスポンス

コマンドの中にはエラーを返す物があります。

エラーレスポンスは通常のレスポンスと同じ type を伴って返されますが、通常のレスポンスとは異なる statusCode と body を持ちます。大まかなエラーの種類は statusCode で示され、詳細な情報は body の内容として返されます。

コマンドが複数のボリュームに分散して処理されて、各ボリュームがエラーを返した場合、レスポンスメッセージは errors フィールドを持ちます。各ボリュームから返されたエラーは以下のように保持されます：

{
  "type"       : "add.result",
  "inReplyTo"  : "...",
  "statusCode" : 400,
  "body"       : {
    "name":    "UnknownTable",
    "message": ...
  },
  "errors"     : {
    "/path/to/the/node1" : {
      "statusCode" : 400,
      "body"       : {
        "name":    "UnknownTable",
        "message": ...
      }
    },
    "/path/to/the/node2" : {
      "statusCode" : 400,
      "body"       : {
        "name":    "UnknownTable",
        "message": ...
      }
    }
  }
}

このような場合、すべてのエラーの中で代表的な1つがメッセージの body に出力されます。

エラーレスポンスのステータスコード

エラーレスポンスのステータスコードはHTTPのステータスコードに似ています。

400 およびその他の 4xx のステータス
リクエストのメッセージが原因でのエラーであることを示します。
500 およびその他の 5xx のステータス
Droonga Engine内部のエラーであることを示します。

エラーレスポンスの body

エラーレスポンスの body の基本的な形式は以下の通りです。

{
  "name"    : "<エラーの種類>",
  "message" : "<人間が読みやすい形式で示されたエラーの詳細>",
  "detail"  : <任意の形式の、追加のエラー情報>
}

追加の情報がない場合、 detail は出力されないことがあります。

エラーの種類

すべてのコマンドに共通するエラーとして、以下の物があります。

MissingDatasetParameter
dataset の指定がないことを示します。ステータスコードは 400 です。
UnknownDataset
指定されたデータセットが存在しないことを示します。ステータスコードは 404 です。
UnknownType
type に指定されたコマンドを処理するハンドラが存在しない、未知のコマンドであることを示します。ステータスコードは 400 です。