Heroku API设计指南：HTTP+JSON一致性原则

"HTTP API 设计指南"是一份深入介绍HTTP+JSON API设计模式的文档，它借鉴自Heroku平台的API设计指南。该指南不仅涵盖了Heroku现有API的详细说明，还展示了未来内部API的发展方向，旨在使非Heroku员工也能理解和遵循这一设计规范。核心目标是追求一致性、聚焦业务逻辑并避免过度设计，寻找一种实用而非理想化的API设计方法。 学习该指南的前提是读者已具备基本的HTTP+JSON API设计知识。内容分为四个章节： 1. **基础**： - 隔离关注点：强调设计时应将请求处理与响应结构分离，简化开发过程。 - 强制使用安全连接（SecureConnections），确保数据传输的安全性。 - 提供版本号在Accept头信息中，便于API版本管理。 - 支持ETag缓存，提高性能。 - 使用Request-Id在请求中进行内省，便于跟踪和调试。 - 对大响应进行范围拆分，提高响应效率。 2. **请求（Requests）**： - 返回合适的状态码，明确告知请求结果。 - 提供所有可用资源，增强功能性。 - 要求请求体使用JSON格式，保持数据标准化。 - 统一资源路径格式，便于理解和扩展。 - 小写路径和属性名称，遵循编程约定。 - 支持无ID间接引用，简化资源操作。 - 减少路径嵌套，减少复杂度。 3. **响应（Responses）**： - 包含资源的唯一标识（UU ID）。 - 提供标准的时间戳，通常使用UTC和ISO8601格式。 - 处理外键关系，清晰展现数据结构。 - 错误处理应生成结构化的错误信息，易于理解。 - 显示频率限制状态，合理控制API使用。 - 确保响应JSON的最小化，优化性能。 4. **工件（Artifacts）**： - 注重API的可读性和文档性，提供易于理解的示例。 - 描述API的稳定性，明确预期行为。 - 默认JSON输出应该易于阅读和打印，提升用户体验。 这份指南提供了实用的指导原则和最佳实践，帮助开发者创建高效、一致且易于使用的HTTP+JSON API。无论是对现有API的开发者还是对API设计感兴趣的人员，都能从中获益。