对于 API 设计,这个演示稿讲得实存是太赞了,等不及的同学马上了解一下《RESTful API Design, Second Edition》的这 107 页吧。如果希望先听我讲讲 10 分钟收获的同学,可以先看下面的描述。
以为需要买本书,看完整本才能明白什么是好的接口。没想到,利用 HTTP Verbs 和 URL,可以这样做非常简洁的 API。“对牛弹琴”被用以描述做无效劳动,可见弹琴者几乎做的都是无用功,而作者以深入浅出的方式让牛听懂琴变成了 — 甚至像我这样的牛 — 在 10 分钟之内立马理解。其主要需要注意的点可以归纳为以下几句:
保持 RESTful。只需 2 种 URL。不使用动词。使用复数名词。具体优于抽象。提供 JSON 的原则是支持 JS 调用。把复杂的参数放于 ? 号后面。借鉴优秀的 API。提供异常描述。提供库或者 SDK。
这里面值得强调,或者说可能需要一点解析的是这几点:
一、只需 2 种 URL
结合 HTTP Verbs,我们通常只需要 2 种 URL,一种用于集合的调用,一种用于单个实例的调用:
- /dogs :用于调用狗狗列表
- /dogs/1234 用于调用 dogs 这个列表中 ID 为 1234 的小狗
所有 API 都一样。其实我想你想到的可能是这样的形式,因为毕竟会需要有四种动作:创建 / 查看 / 修改 / 删除
- /dogs [GET] 查看狗狗列表
- /dogs/edit [PUT] 批量修改
- /dogs/delete [DELETE] 批量删除
- /dogs/1234 [GET] 查看 ID 为 1234 的小狗
- /dogs/1234/edit [PUT] 对小狗做点什么
- /dogs/1234/delete [DELETE] 删除小狗的存在
看起来不错。或者还可以变成 /dogCreate 之类的来减少一层,但还是不能实质上减少数目。这时太多接口总是导致记错,并且还需要记得 HTTP Verbs 与 URL 的对应。代码层面上也比较难做(或者应该对比下后面的实现)。何不考虑与 HTTP Verbs 结合:
- POST –> Create 创新
- GET –> Read 查看
- PUT –> Update 修改
- DELETE –> Delete 删除
这个时候我们只需要 2 种 URL,与 HTTP Verbs 充分结合:
POST | GET | PUT | DELETE | |
---|---|---|---|---|
/dogs | 创建 | 查看列表 | 批量修改 | 删除所有 |
/dogs/1234 | error | 查看单个实例 | 修改单个实例 | 删除单个实例 |
二、提供 JSON 的原则是支持 JS 调用
这点似乎一点难理解,先让我们来看一下几个设计吧:
// twitter "created_at": "Thu Nov 03 05:19:38 +0000 2011" //bing "DateTime": "2011-10-29T09:35:00Z" //Foursquare "createdAt": 1320296464
这里假设我们有两种需要,一种是直接放入页面显示,一种是做计时器用,那么当我们拥有的两个变量,在 bing 和 4sq 上是这样的:
var obj = JSON.parse(response); // bing var stamp = obj.DateTime; // 返回 2011-10-29T09:35:00Z // 显示出来也看得出是一个日期 // 但不能做计数器用,需要转换,这种格式 JS 还不好转 // 4sq var stamp = obj.createdAt; // 返回 // 显示出来需要用 JS 转 1320296464,因为是秒数,可以方便转成各种格式 // 可直接用于计数
显然,这种方式更灵活。API 最好支持 JS 直接调用/使用。
三、把复杂的变量放在 URL 参数上
这个如上面第一点所提到的,层级导致代码的难度增大,不如放成参数;这样还可以保证 API 接口的简洁和少量,而实现同样多的功能。
然后,或者你会像我一样,再一次阅读。然后去迭代/优化你的 API。