REST GET API 的推荐日期格式答案

【问题标题】：Recommended date format for REST GET APIREST GET API 的推荐日期格式
【发布时间】：2012-03-23 19:30:37
【问题描述】：

对于这样的 REST GET API，推荐的时间戳格式是什么：

http://api.example.com/start_date/{timestamp}

我认为实际的日期格式应该是 ISO 8601 格式，例如 YYYY-MM-DDThh:mm:ssZ 表示 UTC 时间。

我们是否应该使用不带连字符和冒号的 ISO 8601 版本，例如：

http://api.example.com/start_date/YYYYMMDDThhmmssZ

或者我们应该使用例如 base64 编码对 ISO 8601 格式进行编码？

【问题讨论】：

为什么 ISO 8601 格式不适合您？
@Johannes ISO 8601 格式（在没有连字符和冒号的版本中）可以，我只是想知道是否有一种推荐的方法来表示 URL 中的日期

标签： http url rest date get

【解决方案1】：

查看这篇文章了解 API 日期和时间的 5 条定律HERE：

法律 #1：使用 ISO-8601 作为日期
法则 #2：接受任何时区
法则 #3：将其存储在 UTC 中
法则 #4：以 UTC 格式返回
法则 #5：不要在不需要的时候浪费时间

文档中的更多信息。

【讨论】：

-1，因为2017-11-20T11%3A00%3A00Z 的可读性不太好。此外（特定于 IIS）它似乎对 URL 中的冒号非常偏执即使它们是编码的。
此链接 - agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates 建议使用整数 epoch 以避免 iso-8601 格式可能遇到的人类可读性问题。如果您有不同的看法，请告诉我。
请注意，连字符和点不是 URL 中的保留字符。只有冒号需要 URL 编码 (en.wikipedia.org/wiki/Percent-encoding)。在 ISO-8601 (en.wikipedia.org/wiki/ISO_8601) 中，连字符是必需的，但冒号是可选的。因此，如果您需要更高的精度，在 URL 中使用的正确 ISO-8601 变体是 YYYY-MM-DDThhmmssZ 和 YYYY-MM-DDThhmmss.mmmZ。
一篇经常链接和激烈辩论的文章。虽然我同意选择可排序的格式如果它必须是字符串，但 unix 时间戳（本文甚至没有承认）具有所述的每一个好处，甚至更多。在演示之前，时区和夏令时（以及政治决策）的问题甚至都不存在。

【解决方案2】：

REST 没有推荐的日期格式。实际上，它归结为最适合您的最终用户和系统的方法。就个人而言，我想坚持像您对 ISO 8601（url 编码）的标准。

如果没有丑陋的 URI 是一个问题（例如，在你的 URI 中不包括 :、-、的 url 编码版本）并且（人类）可寻址性不那么重要，你也可以考虑 epoch时间（例如http://example.com/start/1331162374）。 URL 看起来更简洁一些，但您肯定会失去可读性。

/2012/03/07 是您经常看到的另一种格式。我想你可以扩展一下。如果您走这条路线，只需确保您始终处于 GMT 时间（并在您的文档中明确说明），或者您可能还想包含某种时区指示器。

归根结底，它归结为对您的 API 和最终用户有效的方法。您的 API 应该为您工作，而不是您为它工作 ;-)。

【讨论】：

谢谢，非常有用的答案。我想我会选择 ISO 8601 的压缩版本（即http://api.example.com/start_date/YYYYMMDDThhmmssZ），它有利于可读性和干净的 URL。
但 JSON 确实有推荐的日期格式，它是 ISO 8601 :)
@RaduPotop 是的，但这是我们正在谈论的 HTTP 和 URI 标准。我不确定 JSON 与它有什么关系。
我只想指出，连字符不需要进行 URL 编码。
此链接 -agiletribe.wordpress.com/2015/06/10/jsonrest-api-handling-dates 建议使用整数 epoch 以避免 iso-8601 格式可能遇到的人类可读性问题。如果您有不同的看法，请告诉我

【解决方案3】：

输入/输出中的每个日期时间字段都需要采用 UNIX/epoch 格式。这避免了 API 不同方面的开发人员之间的混淆。

优点：

Epoch 格式没有时区。
Epoch 具有单一格式（Unix 时间是一个带符号的数字）。
纪元时间不受夏令时的影响。
大部分后端框架和所有原生 ios/android API 都支持纪元转换。
本地时间转换部分可以完全在应用程序端完成，具体取决于用户设备/浏览器的时区设置。

缺点：

转换为 UTC 以便以 UTC 格式存储在数据库中的额外处理。
输入/输出的可读性。
GET URL 的可读性。

注意事项：

Timezones are a presentation-layer problem!你的大部分代码不应该处理时区或本地时间，它应该是传递 Unix 时间。
如果您想存储人类可读的时间（例如日志），请考虑将其与 Unix 时间一起存储，而不是代替 Unix 时间。

【讨论】：

不能再同意了。
我唯一要补充的是从一开始就考虑是否需要考虑系统中任何地方的毫秒数。如果是这样，请使用毫秒版本的 Unix 时间戳。

【解决方案4】：

RFC6690 - Constrained RESTful Environments (CoRE) Link Format 没有明确说明日期格式应该是什么，但是在section 2. Link Format 中它指向 RFC 3986。这意味着应该使用RFC 3986 中的日期类型建议。

基本上RFC 3339 Date and Time on the Internet 是要查看的文档，上面写着：

用于 Internet 协议的日期和时间格式 ISO 8601 标准的概况，用于表示日期和使用公历的时间。

这归结为：YYYY-MM-ddTHH:mm:ss.ss±hh:mm

（例如 1937-01-01T12:00:27.87+00:20）

是最安全的选择。

【讨论】：

【解决方案5】：

始终使用 UTC：

例如，我有一个计划组件，它接受一个参数 DATETIME。当我使用 GET 动词调用它时，我使用以下格式，其中传入的参数名称是 scheduleDate。

示例：
https://localhost/api/getScheduleForDate?scheduleDate=2003-11-21T01:11:11Z

【讨论】：