4. 共通定義¶

4.1. JSON¶

REST API は、多くの場面で JSON を使用する。

JSON の記法については JSON を参照のこと。

JSON の value には、JSON の仕様通り、以下のものが指定できる。

オブジェクトストレージの利用時には、MongoDB の Extended JSONを利用できる。 MongoDB拡張JSONの仕様については Extended JSON を参照のこと。

Extended JSON には Canonical, Relaxed の2種類のフォーマットがある。投入時にはいずれのフォーマットも受け付けるが、BaaSサーバが返却するフォーマットは常に Relaxed となる。

なお、"_id" プロパティの値については、自動的に ObjectId への変換が行われる。具体的には、投入時に ObjectId 型へ変換され、返却時には文字列型に変換される。

JSONのプロパティ名は、原則としてすべて camelCase とする(先頭文字を小文字、単語区切りを大文字。アンダースコアは使用しない)。なお、以下のプロパティ名は予約語とし、別の目的では使用できないものとする。

日付は ISO 8601日付形式の文字列として、以下のフォーマットで表現する。:

YYYY-MM-DDThh:mm:ss.sssZ

タイムゾーンは UTC 固定とする。秒は小数点以下３桁に固定する。

以下に例を示す。:

2018-08-07T09:12:53.789Z

上記日付表記は、作成日時(createdAt)や更新日時(updatedAt)などで使用される。

なお、オブジェクトストレージにおいて、これ以外のフォーマットでユーザ定義の日時文字列をユーザ定義フィールドに格納することは自由であり、特に制限はない。

エラー時に返却するステータスコードは、各 API の「レスポンスコード」に記載しているが、これ以外に以下のステータスコードが返る場合がある。

レスポンスが JSON 形式である REST API においてエラーが発生した場合は、以下の JSON フォーマットでエラーが通知される。

{
    "error": "error messages..."
}

ただし、各 API の説明において別のエラーレスポンスが定義されている場合はこの限りではない。

ほぼすべての API 呼び出しにおいて、以下２つのヘッダは必須である。

以下ヘッダは、セッショントークンを送信するために使用する。

セッショントークンは、ログインAPI発行時にサーバからクライアントに発行され、ログアウト時に破棄される。 API 発行時の X-Session-Token の送信ルールは以下の通りである。

なお、各 API の説明で X-Session-Token が「必須」となっている場合、セッショントークンを送信せずに API を呼び出すとエラーを返却する (X-Session-Token を付けずに API を呼び出してはならない、という意味ではない)。

また、X-Session-Token が記載されていない場合、サーバは X-Session-Token を参照しない (送信してはならない、という意味ではない)

なお、Basic認証またはクライアント証明書認証を使用する場合は、X-Session-Token を省略することができる。

各APIに記載している「Query Parameters」は、クエリパラメータとして URL の query 部に指定すること。クエリパラメータは特に指定されていない限り、オプションであり必須ではない。

また、各APIでは特に明記していないが、クエリパラメータはすべて適切に URLエンコードすること。