タイムゾーン変換 API の設計 - 堅牢な時刻変換エンドポイントの実装指針

API 設計の基本判断 - 入力と出力の形式

タイムゾーン変換 API の設計で最初に決めるべきは、入力と出力の時刻形式です。入力は ISO 8601 形式 (2026-05-15T16:00:00+09:00) を必須とし、タイムゾーン情報を含まない文字列は拒否すべきです。オフセットなしの入力を受け付けると「この時刻はどのタイムゾーンか」という曖昧さが生じ、バグの温床になります。

変換先のタイムゾーン指定には、UTC オフセット (+09:00) ではなく IANA タイムゾーン名 (Asia/Tokyo) を使用します。オフセットはある瞬間の時差を表すに過ぎず、サマータイムの切り替えを表現できません。America/New_York と指定すれば、API 側で入力時刻がサマータイム期間かどうかを判定し、適切なオフセット (-4 または -5) を自動的に適用できます。

サマータイム遷移の安全な処理

サマータイムの切り替え時には「存在しない時刻」と「重複する時刻」が発生します。春の切り替え (例: 2:00 AM → 3:00 AM) では 2:00〜2:59 が存在せず、秋の切り替え (例: 2:00 AM → 1:00 AM) では 1:00〜1:59 が 2 回出現します。API はこれらのケースを明示的に処理する必要があります。

存在しない時刻が入力された場合の選択肢は 3 つです。エラーを返す、切り替え後の時刻に丸める (2:30 → 3:00)、または切り替え前の時刻に丸める (2:30 → 1:30)。重複する時刻の場合は、どちらのオフセットを適用するかをクライアントに選択させるか、デフォルトルール (通常は切り替え前のオフセット) を適用します。いずれの場合も、レスポンスに「調整が行われた」旨のフラグを含めることで、クライアント側が判断できるようにします。

IANA データベースの管理 - 更新頻度と互換性

IANA タイムゾーンデータベース (tzdata) は年に 3〜10 回更新されます。各国がサマータイムの廃止や変更を決定するたびに新しいバージョンがリリースされるため、API サーバーの tzdata を最新に保つ運用が不可欠です。古い tzdata を使い続けると、特定の国の時刻変換が誤った結果を返す事態が発生します。

tzdata の更新には後方互換性の問題が伴うことがあります。タイムゾーン名の統合 (例: Asia/Calcutta → Asia/Kolkata) や、過去の履歴データの修正が行われる場合があるためです。API は廃止されたタイムゾーン名をエイリアスとして受け付けつつ、レスポンスには正規名を返す設計が推奨されます。

エラーハンドリング - 明確なエラーレスポンス

タイムゾーン変換 API で発生しうるエラーは多岐にわたります。不正な日時形式、存在しないタイムゾーン名、サポート範囲外の日付 (遠い過去や未来)、存在しない時刻 (サマータイムギャップ) などです。各エラーに対して、HTTP ステータスコードだけでなく、機械可読なエラーコードと人間可読なメッセージを返すべきです。

特に注意すべきは「部分的に正しい入力」の扱いです。2026-02-30T10:00:00+09:00 (2 月 30 日は存在しない) のような入力を、ライブラリによっては 3 月 2 日に自動補正してしまうことがあります。API としては、このような暗黙の補正は行わず、明示的にエラーを返すのが安全です。クライアントが意図しない日付で処理が進むことを防ぎます。

パフォーマンスとキャッシュ戦略

タイムゾーン変換自体は計算コストが低い処理ですが、大量のリクエストを処理する場合はキャッシュが有効です。ただし、キャッシュキーの設計には注意が必要です。同じ入力時刻と変換先タイムゾーンの組み合わせでも、tzdata のバージョンが変わると結果が変わる可能性があるため、キャッシュの無効化タイミングを tzdata の更新に連動させる必要があります。

バッチ変換エンドポイント (複数の時刻を一度に変換) を提供することで、クライアント側の HTTP リクエスト数を削減できます。カレンダーアプリケーションが 1 か月分の予定を異なるタイムゾーンで表示する場合、30 回の個別リクエストではなく 1 回のバッチリクエストで処理できれば、レイテンシーとサーバー負荷の両方が改善されます。