REST APIとJSONでの日付フォーマット
REST APIとJSONペイロードでの日付フォーマットのベストプラクティス。ISO 8601、Unixタイムスタンプ、RFC 3339、API設計でのタイムゾーン情報の処理を解説。
Practical
詳細な説明
APIとJSONでの日付フォーマット
APIの日付フォーマット選択は、相互運用性、タイムゾーン処理、開発者体験に影響する重要な設計決定です。
3つの主要アプローチ
1. ISO 8601 / RFC 3339文字列
{ "created_at": "2026-02-28T14:30:00Z" }
2. Unixタイムスタンプ（整数）
{ "created_at": 1772236800 }
3. カスタム文字列フォーマット
{ "created_at": "02/28/2026 2:30 PM" }
推奨：ISO 8601 / RFC 3339
業界のコンセンサスはISO 8601（特にRFC 3339）の使用です：
理由：
- 人間可読 — 開発者がペイロードを視覚的に検査可能
- タイムゾーン対応 — オフセットが文字列の一部
- 広くサポート — すべての言語にパーサーが組み込み
- ソート可能 — 辞書順ソート = 時系列ソート
- 業界標準 — GitHub、Stripe、Twilio、AWSが使用
API設計のベストプラクティス
- 常にタイムゾーン情報を含める
- 保存にはUTCを使用
- フォーマットをドキュメント化
- 一貫性を保つ — すべての日付フィールドで同じフォーマット
- デフォルトは秒精度 — 必要な場合のみミリ秒を追加
ユースケース
日付フォーマットの決定はすべてのAPIコンシューマーに影響します。REST API設計、GraphQLスキーマ定義、Webhookペイロード仕様、SDKおよびクライアントライブラリ実装、APIドキュメント、タイムスタンプカラムのデータベーススキーマ設計に関連します。