[ADP-703] 日期時間和時間欄位慣例
指導原則
- 應該(SHOULD)為日期時間欄位加上
At後綴，而不是簡單地使用time或timestamp。 - 可以(MAY)使用常見術語來表示日期或時間相關的欄位，包括:
time、date、timestamp、day。 - 必須(MUST)使用 RFC 3339 格式來表示日期時間和時間值。
設計思路
添加 At 後綴明確表示該欄位是日期時間格式，而不是普通字串。雖然你可以查看文件了解字串格式，但一個好的 API 應該能夠語義化地描述自己。
如果時間的語義意義不清楚，使用常見術語如 time/timestamp/date/day 是可以接受的。例如，在 CloudEvents 中，定義了一個 time 欄位，但沒有明確的含義（創建時間或當前時間）。
關於值的表示，請參見使用 RFC 3339 格式表示日期時間和時間的要求。
RFC3339 格式概覽
參閱原始規範或 RFC3339概覽
示例
正確做法:
json
{
"startAt": "2023-10-12T08:00:00Z",
"endAt": "2023-10-12T10:00:00Z"
}錯誤做法:
json
{
"start": "2023-10-12T08:00:00Z",
"end": "2023-10-12T10:00:00Z",
"occur": "2023-10-12T10:00:00Z"
}