响应
最后更新于：2022-04-01 00:19:19
## 总是提供资源(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;`）。