基础

总是使用TLS

总是使用TLS（就是https）来访问API，没有必要指出什么时候需要用，什么时候不需要用，只管任何时候都用它就好。

对所有非TLS的请求返回403 Forbidden，不要用重定向，这会允许一些不良的客户端行为，而又没有任何好处。依赖重定向的客户端会使流量翻倍，而让TLS毫无意义 —— 敏感数据已经在第一次请求时发送出来了。

在Accepts头中带上版本号

从一开始就为API分配版本。使用Accepts头来发送版本信息，可以使用自定义的内容类型，如：

Accept: application/vnd.heroku+json; version=3

不要提供默认版本，而由客户端显式指定它使用哪一个特定的版本。

通过Etags支持缓存

在所有的请求中带上 ETag 头 ， 用于识别特定版本的返回资源。用户可以在随后的请求中通过提供If-None-Match头的值来检查内容是否过期。

用Request-Ids追踪请求

在每个API相应中提供Request-Id头，带上一个唯一的UUID值。如果服务器和客户端都记录了这些值，在跟踪和调试请求时会派上大用场。

用Ranges来分页

对所有可能产生大量数据的响应进行分页。使用Content-Range 头来标记分页请求。可以参考这个例子，来了解请求和响应头、状态码、Limit、排序和翻页：Heroku Platform API on Ranges