## 基础 ### 隔离关注点 设计时通过将请求和响应之间的不同部分隔离来让事情变得简单。保持简单的规则让我们能更关注在一些更大的更困难的问题上。 请求和响应将解决一个特定的资源或集合。使用路径(path)来表明身份,body来传输内容(content)还有头信息(header)来传递元数据(metadata)。查询参数同样可以用来传递头信息的内容,但头信息是首选,因为他们更灵活、更能传达不同的信息。 ### 强制使用安全连接(Secure Connections) 所有的访问API行为,都需要用 TLS 通过安全连接来访问。没有必要搞清或解释什么情况需要 TLS 什么情况不需要 TLS,直接强制任何访问都要通过 TLS。 理想状态下,通过拒绝所有非 TLS 请求,不响应 http 或80端口的请求以避免任何不安全的数据交换。如果现实情况中无法这样做,可以返回`403 Forbidden`响应。 把非 TLS 的请求重定向(Redirect)至 TLS 连接是不明智的,这种含混/不好的客户端行为不会带来明显好处。依赖于重定向的客户端访问不仅会导致双倍的服务器负载,还会使 TLS 加密失去意义,因为在首次非 TLS 调用时,敏感信息就已经暴露出去了。 ### 强制头信息 Accept 中提供版本号 制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以,最好在设计之初就使用一些方法来预防可能会遇到的问题。 为了避免API的变动导致用户使用中产生意外结果或调用失败,最好强制要求所有访问都需要指定版本号。请避免提供默认版本号,一旦提供,日后想要修改它会相当困难。 最适合放置版本号的位置是头信息(HTTP Headers),在 `Accept` 段中使用自定义类型(content type)与其他元数据(metadata)一起提交。例如: ~~~ Accept: application/vnd.heroku+json; version=3 ~~~ ### 支持Etag缓存 在所有返回的响应中包含`ETag`头信息,用来标识资源的版本。这让用户对资源进行缓存处理成为可能,在后续的访问请求中把`If-None-Match`头信息设置为之前得到的`ETag`值,就可以侦测到已缓存的资源是否需要更新。 ### 为内省而提供 Request-Id 为每一个请求响应包含一个`Request-Id`字段,并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值,它能主我们提供一种机制来跟踪、诊断和调试请求。 ### 通过请求中的范围(Range)拆分大的响应 一个大的响应应该通过多个请求使用`Range`头信息来拆分,并指定如何取得。详细的请求和响应的头信息(header),状态码(status code),范围(limit),排序(ordering)和迭代(iteration)等,参考[Heroku Platform API discussion of Ranges](https://devcenter.heroku.com/articles/platform-api-reference#ranges).