API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载导读本篇文章围绕 HTTP API Design Guide源自 Heroku Platform API 设计实践的开源 API 设计指南仓库中 Responses 章节的「Provide standard timestamps」规范展开讲解如何在 HTTPJSON API 中为资源对象默认提供created_at与updated_at两个标准时间戳字段。读完本文你将掌握该规范的确切表述与 JSON 示例、与之配套的 UTC/ISO8601 时间格式要求见 时间格式规范理解何时可以合理地省略这两个字段并了解该规范与仓库中 UUID、完整资源返回、JSON 压缩、标准响应类型等相邻规范之间的协同关系可直接用于你自身 API 的响应建模与评审。一、规范原文默认提供 created_at 与 updated_aten/responses/provide-standard-timestamps.md是这份指南中 Responses响应章节的一条独立子规范全文要点可概括为为资源默认提供created_at和updated_at时间戳。这条规则看似简单却奠定了整个 API 资源对象的时间语义基础。它要求所有资源在默认情况下都携带两个字段created_at资源创建的时间updated_at资源最近一次被修改的时间。该规范所在的 Responses 章节见 en/responses/README.md是一组响应模式约定它与「提供资源 UUID」provide-resource-uuids.md并列共同构成 API 返回资源对象时的最小字段约定每个资源默认拥有id、created_at、updated_at。从这份指南的整体目录en/SUMMARY.md可以看到Responses 章节还包含完整资源返回、标准响应类型、结构化错误、限流状态等十余条规范时间戳是其中与资源元数据直接相关的核心条目。二、标准时间戳的 JSON 示例规范原文给出了一个资源对象的时间戳示例JavaScript 对象字面量形式{ // ... created_at: 2012-01-01T12:00:00Z, updated_at: 2012-01-01T13:00:00Z, // ... }要点解读字段命名使用created_at/updated_at这种 snake_case 命名与指南 Requests 章节中「downcase paths and attributes」的要求见 en/requests/downcase-paths-and-attributes.md保持一致——属性一律小写。字段位置示例中时间戳以// ...省略号包围表明它们是资源对象中的附加字段应与id、业务属性如hostname、email等并列平铺在资源对象顶层。值格式示例2012-01-01T12:00:00Z是带ZUTC 标识的 ISO8601 字符串不是 Unix 毫秒数字也不是不带时区的本地时间字符串。三、时间戳的格式底线UTC 时间 ISO8601 渲染单看provide-standard-timestamps.md只定义了要有哪两个字段而格式层面由姊妹规范 use-utc-times-formatted-in-iso8601.md 补齐只接受和返回 UTC 时间并以 ISO8601 格式渲染时间。该规范给出的示例为finished_at: 2012-01-01T12:00:00Z将两条规范合在一起一个资源时间戳字段的完整约束是时区必须为 UTC以Z结尾禁止返回带08:00偏移的本地时区时间禁止返回不带时区标识的时间字符串格式ISO8601 扩展格式形如YYYY-MM-DDTHH:MM:SSZ载体以 JSON 字符串类型承载对应标准响应类型中对 String 的约定见 provide-standard-response-types.md。之所以统一采用 UTCISO8601是因为 API 面向全球客户端客户端无需解析偏移量或猜测服务器时区字符串即自含语义且 ISO8601 是排序友好的文本格式字符串字典序即时间序。四、何时可以省略语义驱动的例外规范原文在给出默认提供的主规则后紧接着补充了例外条件这些时间戳对某些资源可能没有意义在这种情况下可以省略。这是一个需要 API 设计者自行裁量的语义判断指南没有给出封闭的清单但结合该仓库其他规范可以从两个角度理解字段无业务语义的资源例如仅作为瞬时计算结果的聚合值、内部中间态对象、以及生命周期短到无需追踪创建/修改历史的资源created_at/updated_at便没有意义可以省略。异步/临时操作的响应注意「提供完整资源」规范provide-full-resources-where-available.md明确指出202 Accepted 响应不会包含完整资源表示示例返回空对象{}——此时自然也不含时间戳而 200/201 响应应返回完整资源其中就包含created_at/updated_at。因此设计时的判断准则是只要一个资源具有可追踪的创建与修改语义就应该默认带上这两个字段只有当字段确实失去语义价值时才省略且应在 API 文档中注明。五、时间戳与其他响应规范的协同该仓库的响应规范是一套相互咬合的约定时间戳规范与它们的配合关系如下相邻规范与时间戳的关系provide-resource-uuids.md资源默认同时拥有idUUID与时间戳二者共同构成资源元数据UUID 示例同样采用2012-01-01T12:00:00Z风格的字符串时间戳与之并列出现provide-full-resources-where-available.md200/201 响应返回完整资源对象其示例正文中created_at、updated_at与hostname、id并列是完整资源的组成部分keep-json-minified-in-all-responses.md实际响应中 JSON 应压缩传输时间戳字段与其它字段一样以紧凑形式输出如{id:...,created_at:2012-01-01T12:00:00Z,...}避免多余空白增大响应体积provide-standard-response-types.md时间戳属于 String 类型取值只能是字符串或null不能出现布尔值或数字形式的时间use-utc-times-formatted-in-iso8601.md时间戳的格式底线UTC ISO8601一个符合全部规范的真实响应片段综合 keep-json-minified-in-all-responses.md 中的压缩示例形如{beta:false,email:aliceheroku.com,id:01234567-89ab-cdef-0123-456789abcdef,last_login:2012-01-01T12:00:00Z,created_at:2012-01-01T12:00:00Z,updated_at:2012-01-01T12:00:00Z}六、落地到自有 API 的实现建议虽然本仓库是一份纯文档形式的 API 设计指南不含服务端代码实现但其规则可直接映射到常见后端实践数据库建模为资源表统一维护created_at、updated_at两个列或字段在写入时填充创建时间、在更新时刷新修改时间序列化层始终以 ISO8601 UTC 字符串输出。序列化层约定为资源对象的序列化器约定统一的字段名created_at/updated_at避免因语言习惯产生createTime、updatedTime等命名漂移从而破坏客户端契约。客户端处理客户端可直接按字符串解析 ISO8601无需处理时区换算如需排序可按字符串字典序如需精确比较再转换为内部时间对象。文档声明若某资源确实省略时间戳应在 API 参考文档中明确标注该资源不提供创建/修改时间遵循仓库 Artifacts 章节「提供人类可读文档」的思路见 en/SUMMARY.md 中 Artifacts 部分避免客户端误判。总结「Provide standard timestamps」是 http-api-design 指南中成本最低、收益最直接的响应规范之一只需约定created_at/updated_at两个字段、默认提供、按 UTCISO8601 渲染、无语义时允许省略就能为所有 API 客户端提供统一、可预测、可排序的资源时间语义。将它与仓库中 UUID、完整资源、压缩 JSON、标准类型等相邻规范en/responses/README.md配套使用即可构建一套自洽且便于评审的 HTTPJSON 响应约定。赞分享API设计教程【免费下载链接】http-api-designHTTP API design guide extracted from work on the Heroku Platform API项目地址https://gitcode.com/gh_mirrors/ht/http-api-design点击查看免费下载相关推荐HTTP API 设计指南http-api-design为每个资源默认提供全局唯一的 UUID 标识HTTP API 设计指南http api design为每个资源默认提供全局唯一的 UUID 标识 导读 本篇文章聚焦 http api designAPI设计教程HTTP API 设计指南为 JSON 响应定义标准数据类型http-api-designHTTP API 设计指南为 JSON 响应定义标准数据类型http api design 导读 本篇文章基于开源仓库 http api design hAPI设计教程security-audit-skill最高原则只确认已成立的边界失效其他都不算漏洞security audit skill最高原则只确认已成立的边界失效其他都不算漏洞 security audit skill 是一个让编码智能体变身安全审AI 技能应用安全上一篇Boost.Beast完全指南构建高性能HTTP和WebSocket应用下一篇PS3 存档转换指南实机↔RPCS3 双向导入三步走通附排错速查表创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考