WebAPI の GET パラメータとして「開始日時」「終了日時」を指定するような時に使える、ISO 8601 の Time intervals (period of time) フォーマットについて紹介します。
ISO 8601 とは？
日付と時刻を表現するフォーマットを定めた国際規格です。以下のような文字列で表現されます。
YYYY-MM-DDThh:mm:ss※末尾にUTC の場合は Z、JSTの場合は +09:00 を指定- e.g.
2019-09-20T21:29:58+09:00
一般的に公開されている各種サービスの WebAPI で、日付とタイムスタンプのような時刻を表現するフォーマットとして広く使われています。詳細については Wikipedia になってしまいますがこちらを参照してください。
ちなみに、ISO 8601 のオフィシャルな仕様書は有料となっています。気になる方はチェックしてみてください。
- ISO 8601-1:2019 - Date and time – Representations for information interchange – Part 1: Basic rules
- ISO 8601-2:2019 - Date and time – Representations for information interchange – Part 2: Extensions
ISO 8601 については多くの言語／ライブラリにてサポートされており、ISO 8601 形式での出力やパース、Validation などの機能が備わっています。
ISO 8601 の Time Intervals (period of time) とは？
冒頭で記述したように、「開始日時」「終了日時」がある特定の期間を表現する時に使えるフォーマットです。開始日時と終了日時の間に半角スラッシュ/を挟んで記述します。
{開始日時}/{終了日時}- e.g.
2019-08-20T21:29:58+09:00/2019-09-20T21:29:58+09:00
上記の他にもいくつか表現方法はありますが、実装に用いる言語やライブラリの都合を考えて選択すると良さそうです。
何に使える？
例えば日付の属性を持つデータを検索する WebAPI で、startとendまたはfromとtoといった範囲（期間）を指定するパラメータが必要になる場合、まとめてperiodといった一つのパラメータにすることができます。
状況によりますが、パラメータの数が減り、「ISO 8601 Time intervals フォーマットで指定してください」と簡単に明記できるため、WebAPI の仕様をよりシンプルに記述することができます。
いかがだったでしょうか。
簡単な内容でしたが、個人的な経験として WebAPI 仕様を書いていく中で指摘されたことがあり、記事にしてみました。
最後まで読んでいただきありがとうございました。