接上篇
HTTP-API-DESIGN 怎样设计一个合理的 HTTP API (一)
整个 ppt 可以去这里下载。
这一篇主要从服务端应该如何返回合理的返回值的角度,讨论如何设计一个合理的 HTTP-API;
主要有以下几个方面:
- 为每个资源,分配一个 Resource ID(UUID)
- 使用统一的时间戳
- 正确地使用外键
- 将错误响应信息标准化
- 对客户端进行流量控制
- 将发返回的 JSON “最小化”
为每个资源,分配一个 Resource ID(UUID)
返回的结果中,需要为每一个“资源”(用户、消息、评论、私信等等)分配一个唯一的 ID(UUID)。 推荐使用 “8-4-4-4-12” 格式的 UUID,一定不要使用数字,尤其是自增 ID。
避免使用自增 ID 主要从以下几个方面考虑:
- 数字 ID 会暴露总体用户量
- 数字 ID 会使数据抓取变得更容易
- 数字 ID 会有溢出的潜在风险
- 数字 ID 会(不自觉地)使你的代码和 DB 耦合
使用统一的时间戳
继续“资源” 的话题,当我们创建、修改资源时,都需要记录下操作对应的时间。应该在 DB 中,为每一个资源,提供“created_at”', “updated_at”' 信息; 存储、传输时间信息时,应该使用 “ISO8601”格式化过的 “UTC”'(only), 不应该使用其他格式存储时间。
有些人(比如我)更喜欢用unix 时间戳,其实这些习惯,更多的出于对 datetime 库的不熟悉导致的。使用 UTC 的优点还是很多的:
- 为什么不使用 UNIX 时间戳? 不可读,不方便
- 除了这点呢?后台调试不方便(sql select)
- 会有性能问题吗?不会大到影响你的程序
- 我不会用? 找对应语言的 lib
正确使用外键
在 API 返回的结果中,如果某个结果中涉及到了其他“资源”,应该独立标识出它的外键。
比如这样:
{ "name": "service-production", "owner": { "id": "5d8201b0-xxx" } }
下面的方式是错误的:
{ "name": "service-production", "owner_id": "5d8201b0-xxx" }
上面两种方式有什么区别呢? 假设有一天,由于业务需要,你想在结果中,增加一些额外的信息,独立外键的方式,可以很清晰地、不影响原有结果格式地完成任务:
{ "name": "service-production", "owner": { "id": "5d8201b0...", "name": "Alice", "email": "alice@heroku.com" } }
而非独立外键,要么需要增加好多不明的key;要么需要修改原有的数据格式。
将错误响应信息标准化
当某次请求出现错我的时候,需要同时在 header、body 中附上必要的信息,方便API 的调用者清楚问题在哪里。
一般在 header中,返回 resource uri; 在 body 中,要明确标识出错误的 id、提示信息以及请求的 url。
{ "id": "rate_limit", "message": "Account reached its API rate limit.", "url": "https://docs.service.com/rate-limits" }
流量控制
随着用户逐渐增多,一定会出现,客户端请求量变大导致服务器无法响应的情形,此时维护服务的稳定,就变成了服务端、客户端共同的责任。需要约定一套机制,让客户端能够感知到服务端目前的状况,合理安排自身逻辑。 一个合理的解决方案是:利用“RateLimit-Remaining”。
服务端返回“RateLimit-Remaining” 相关信息,客户端根据“RateLimit-Remaining” 的结果,来延长或缩短某些请求的间隔。
Keep JSON minified
为了流量考虑,应该将生成的JSON,剔除空格、换行后返回给客户端。
比如这样:
{"beta":false,"email":"alice@heroku.com","id":"01234567-89ab-cdef-0123-456789abcdef","last_login":"2012-01-01T12:00:00Z","created_at":"2012-01-01T 12:00:00Z","updated_at":"2012-01-01T12:00:00Z"}
那怎么调试呢?可以参考 elastic_search 的实现,让 server 支持一个 pretty 参数,如果在 url 中增加“ pretty=true”, 那么返回的 json 结果将是格式化好、便于阅读的格式。
总结
流水帐似的写了这么多,总结一下吧。
简略地说,作为一个 API 的 Server 端,应该做到:
- 负责人需要 “头脑清醒考虑之”
- 撰写清晰的文档,并且需要与服务保持更新
- 自己负责测试(将测试代码一并提交)
- 提供良好的联调环境
- 使用Resource-ID、Status Code、Rate Limit、pretty 等方式方便调试
- 代码要做到 “宽入严出”
为一个 API 的使用者,应该做到:
- 读文档,读文档,读文档
- 先读文档,再找 Server RD
- 文档中存疑的部分,拒绝猜测的诱惑
- 按照文档的描述,而不是自己的经验来调用 API
- 正确地处理各种服务端的异常 case
- 代码要做到 “宽入严出”