API 设计：让牛懂琴

最新推荐文章于 2025-07-30 10:53:36 发布

寒风问雪

最新推荐文章于 2025-07-30 10:53:36 发布

阅读量445

点赞数

分类专栏：算法设计

算法设计专栏收录该内容

5 篇文章

订阅专栏

对于 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，因为是秒数，可以方便转成各种格式
// 可直接用于计数