## 总是提供资源(UU)ID 为每个资源提供默认的ID属性。除非有特殊理由,总是使用UUID。不要用那些在服务的实例间或资源间不全局唯一的ID,特别是自增ID。 以8-4-4-4-12的格式小写UUID: ~~~ "id": "01234567-89ab-cdef-0123-456789abcdef" ~~~ ## 提供标准的时间戳 为资源提供默认的 `created_at` 和 `updated_at` 时间戳: ~~~ { ... "created_at": "2012-01-01T12:00:00Z", "updated_at": "2012-01-01T13:00:00Z", ... } ~~~ 如果这些时间戳对某些资源真的没有意义,那么你也可以去掉它。 ## 使用ISO8601格式的UTC时间 只接受和返回UTC时间,以ISO8601格式显示: ~~~ "finished_at": "2012-01-01T12:00:00Z" ~~~ ## 嵌入外键数据 将外键引用通过序列化的嵌入对象显示: ~~~ { "name": "service-production", "owner": { "id": "5d8201b0..." }, ... } ~~~ 而不是这样: ~~~ { "name": "service-production", "owner_id": "5d8201b0...", ... } ~~~ 这使得我们可以在inline使用相关的数据,而不需要改变响应的格式,或者引入更多高层的响应字段: ~~~ { "name": "service-production", "owner": { "id": "5d8201b0...", "name": "Alice", "email": "alice@heroku.com" }, ... } ~~~ ## 总是生成结构化的错误信息 为错误生成一致的,结构化的响应Body。包含机器可读的id,人类可读的message,以及可选的url指向关于错误的更多信息,还有如何解决它: ~~~ HTTP/1.1 429 Too Many Requests { "id": "rate_limit", "message": "Account reached its API rate limit.", "url": "https://docs.service.com/rate-limits" } ~~~ 为客户端常见的错误的格式和id撰写文档。 ## 显示频率限制的状态 对客户端的频率限制可以保护服务的健康,并对其他的客户端提供高质量的服务。你可以使用[token bucket](http://en.wikipedia.org/wiki/Token_bucket) 算法 来量化请求限制。 在每次请求的响应头中,通过RateLimit-Remaining 返回剩余的请求次数。 ## 在所有的响应中压缩JSON数据 额外的空格增大了响应的大小,而很多人性化的客户端可以自动美化JSON输出。所以最好将JSON响应进行压缩: `{"beta":false,"email":"alice@heroku.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"}` 不要这样: ~~~ { "beta": false, "email": "alice@heroku.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" } ~~~ 你可以考虑提供一个可选的方式来为客户端输出更长的响应,比如通过请求参数(如`?pretty=true`)或者通过 Accept头(如`Accept: application/vnd.heroku+json; version=3; indent=4;`)。