响应

总是提供资源(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 算法 来量化请求限制。

在每次请求的响应头中，通过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;）。