REST APIのタイムゾーン — 設計パターンと標準

REST APIでのタイムゾーン処理

タイムゾーンを正しく処理するAPIを設計するには、タイムスタンプの送受信方法に関する一貫した規約が必要です。

タイムスタンプフォーマット：常にISO 8601 + UTC

APIレスポンスはISO 8601フォーマットでZサフィックスまたは明示的オフセット付きを使用すべきです：

{
  "createdAt": "2024-03-15T14:30:00Z"
}

リクエストでのユーザータイムゾーン

3つの一般的なパターン：

1. クエリパラメータ：GET /api/events?timezone=America/New_York
2. リクエストヘッダー：X-Timezone: America/New_York
3. ユーザープロファイル設定：サーバーサイドで適用

UTCとローカル時間の両方を返す

ユーザー向けAPIでは、両方を返すと便利です：

{
  "event": {
    "startsAt": "2024-03-15T14:30:00Z",
    "startsAtLocal": "2024-03-15T10:30:00-04:00",
    "timezone": "America/New_York"
  }
}

スケジューリングAPI

スケジューリングエンドポイントでは、ローカル時間とタイムゾーンIDの両方を受け入れます。これにより、サーバーはDST境界を含む各発生の正しいUTC時間を計算できます。

バリデーション

常にサーバーサイドでタイムゾーンIDを検証します：

function isValidTimezone(tz) {
  try {
    Intl.DateTimeFormat(undefined, { timeZone: tz });
    return true;
  } catch {
    return false;
  }
}