HTTP API 设计最佳实践

"HTTP API 设计指南" 这篇指南深入探讨了HTTP+JSON API的设计原则和最佳实践，旨在创建一致、简洁且易于理解的API接口。它源于Heroku平台的API设计经验，不仅适用于Heroku自身的API，也适用于任何希望遵循良好API设计规范的开发者。 ## 强制使用安全连接（Secure Connections） 为了保证数据传输的安全性，所有API请求应强制通过HTTPS协议，以确保数据的加密和防止中间人攻击。 ## 头信息Accept中提供版本号 在请求头中包含`Accept`字段，用于指定API的版本号，允许客户端指定或接收特定版本的API响应，便于版本控制和向后兼容。 ## 支持Etag缓存 利用HTTP的`ETag`头信息，客户端可以通过比较本地缓存的ETag与服务器返回的ETag，判断资源是否已更新，从而实现高效的缓存策略。 ## Request-Id 为每个请求添加`Request-Id`头，帮助追踪请求，便于故障排查和日志分析。 ## 请求范围（Range）拆分响应 对于大型响应，支持`Range`请求头，允许客户端按需获取资源的部分内容，减少网络传输负担。 ### 请求（Requests） - JSON格式数据：请求体使用JSON格式，标准化数据交换格式。 - 统一资源路径：保持资源路径的一致性，简化API接口。 - 小写路径和属性：遵循HTTP协议的约定，使用小写字母。 - 无id间接引用：提供方便的引用方式，无需直接使用资源ID。 - 最小化路径嵌套：避免过多的层级结构，使API更加清晰。 ### 响应（Responses） - 返回合适的状态码：根据操作结果返回相应的HTTP状态码，如200（成功）、404（未找到）、403（禁止访问）等。 - 提供全部可用资源：在响应中包含所有可用的资源信息，以便客户端可以完整处理请求。 - 资源的UUID：每个资源应有一个唯一的标识符（如UUID），便于识别和操作。 - 标准时间戳：使用UTC时间，并遵循ISO8601格式表示时间戳。 - 嵌套外键关系：处理关联关系，通过JSON嵌套结构表示。 - 结构化错误：返回结构化的错误信息，方便客户端解析和处理。 - 显示频率限制状态：告知客户端其请求频率限制，防止过量请求。 - JSON最小化：减少不必要的数据传输，提高性能。 ### 工件（Artifacts） - JSON模式：提供机器可读的JSON模式（如JSON Schema），帮助客户端验证数据结构。 - 人类可读的文档：提供清晰的文档，解释API的用途和使用方法。 - 可执行的例子：提供示例代码，让开发者能够快速了解如何使用API。 - 描述稳定性：明确标注API接口的稳定性和变更情况，方便开发者管理依赖。 译者注强调，通过隔离请求和响应的不同部分，以及保持简单的设计原则，可以简化API设计并专注于更重要的问题。请求由路径、内容和元数据（头信息）组成，查询参数作为补充。所有API操作都针对特定的资源或资源集合，确保了API的高效和针对性。