Kevin Montrose 谈 StackExchange API 的历史与错误

为现有站点创建公开 API 总是一件很有风险的事情，而且 StackExchange 的开放编辑策略则将这种风险更进了一步。在最近发表的一系列文章中，Kevin Montrose 谈到了关于 StackExchange API 的决策以及从中得到的经验与教训。

在开始设计 API 时，他们就已经设定好了目标与约束。比如说，他们的一个主要目标就是“让开发者无需查阅其站点”。StackExchange 成员所遵循的内容许可协定 cc-wiki 可以让第三方重用站点上的内容，但在该 API 发布前，并没有很好的方式进行批量访问。最大的一个约束在于 API 是只读的， Kevin 说到：

显然，写操作是非常危险的。不仅仅出现在有 Bug 的认证上，比如有人以 Jeff Atwood 登录，删除了大量的内容，这会让我寝食难安。更重要的是（也是更危险的），在疏于指导的情况下，这会导致人们发布大量的垃圾信息。 我们为了确保 Stack Exchange 内容的质量付出了艰辛的努力（我们关闭了不满足标准的整个站点）。未经深思熟虑的写操作 API 会导致很多问题，因此我们在 1.0 中并没有将其添加进来。不过，我们有可能在 3.0 中将其添加进来。

Kevin 提到了一些关键的设计点：

• 矢量化请求：“无论何时，如果我们能接受一个 id，那么我们就可以接受 100 个”
• 压缩的响应：我们使用 GZIP 对响应进行压缩，即便客户端并没有要求压缩我们也会这么做
• 排序与过滤：“大多数端点可以接收 sort、min、max、fromdate 以及 todate 参数进行查询”

但人们更感兴趣的是他们所犯的错误。比如说，默认情况下返回总数的决定。

总数对于分页控件的渲染很有用，count(*) 查询就是如此（比如说人们对我的评论的投票数等等）；从这个角度来说，total 字段本身并没有错。但默认情况下返回它则毫无疑问是不对的。 问题在于总数是有用的，但却并非总是如此。很多时候，查询形式是这样的：“返回标记为 X 的最近的 N 个问题 / 答案 / 用户，或是返回你所拥有的前 N 个问题 / 答案并且根据 S 排序”。这些常见的查询与总数没有任何关系，但每次却都要返回总数，这就需要付出代价。

另一个问题在于对隐式类型的使用。相对于显式说明返回哪个数据类型来说，客户端开发者需要从现有的字段中进行推断。无论在何种语言中这都是非常恼人的问题，但对于静态类型语言来说更是如此，因为开发者需要将这些无名类型映射到实际的类上。

暂且不表其他的错误，让我们使用 Kevin 提到的最后一个错误来作为结论，那就是浪费的请求量。为了防止过度使用 API，他们使用了与 Twitter API 一样的配额。

这实在是太浪费带宽了，与 Twitter 不同，我们的配额还是相当慷慨的（每天 10,000 个请求）并且不是动态的。对于 total 字段来说，很多应用并不需要关注配额（除非超过了，但这种情况很少发生），但如果每次请求都获取该字段则需要付出代价。

查看英文原文： Kevin Montrose on the History and Mistakes of the StackExchange API