面向工程师的设计指南 - 什么是好的 Web Api 的设计
Web Api 的重要性
web api 就像一张名片一样，专业的名片可以迅速帮助你与客户之间建立信任感，也可能让你的产品在被使用前，就给客户留下业余，糟糕的负面印象。而一旦客户对你的产品产生负面情绪，这种情绪就会蔓延到产品生态圈甚至于相关公司上。
所以，优雅的 api 设计是成功的产品不可或缺的一部分。
回归主题，对后端工程师来讲，web api 的设计是每天都会接触的工作。在枯燥单调的重复性劳作中，你是否曾经认真思考过好的 web api 设计应该是什么样子的？
别担心。本篇文章围绕 web api 的设计，作者与大家分享一些 api 设计的套路与规范，让你和你的团队也能设计出优雅、健壮、扩展性强的应用程序接口。
什么是优雅的 Web Api
先让我们回顾曾经提到过的关于设计模式的内容：设计模式的精髓在于设计原则，而非模式的生搬硬套。与此类似，优雅的 Web Api 有两个重要原则、如下所示：
- 设计规范明确的内容必须遵守相关规范
- 没有设计规范的内容必须遵守相关事实标准
给自己一些时间，认真阅读并体会上面两个重要原则。
读完上面两个重要原则后，你现在应该依然对如何设计 web api 毫无头绪。别着急，好的创作总是从模仿开始的。
在我们开始长篇大论之前，先通过国际大厂的 web api 示例来观赏一下国际范儿的 web api 长啥样吧。
| 厂名 | uri | 备注 |
|---|---|---|
| api.twitter.com/1.1 | "治国理政平台" | |
| Google Calendar | www.googleapis.com/calendar/v3 | "大厂" |
| api.instagram.com/v1/usrs/search?q=jack | "宠物自拍网站" | |
| api.linkedin.com/v1/people-search | "招工" | |
| Tumblr | api.tumblr.com/v2 | "真的不是成人网站" |
| foursquare | api.foursquare.com/v2/venues/search?q=apple&categoryId=asad123456 | "基于地理位置射交" |
为节约篇幅举例就到此了。如果你觉得示例较少，可自行搜索其他大厂的 Api 示例。
分析这些大厂 Api 端点的设计可以揣摩总结出各种套路规范，供我们模仿学习，这是我们的第一步。
如何设计出国际范儿的 Api 端点？
背口诀
观察和分析上一小节中的国际大厂的设计往往都具备以下几个特点：
- 短小便于输入的 URI。
没人喜欢复杂的单词。
- 人可以读懂的 URI。
名片是拿给人读的。不要把机器码和16进制写到 URI 里。
- 没有大小写混用的 URI。
实际上一般的事实规范是建议全部小写。
- 修改方便的 URI。
api.sample.com/user/:id 傻子都看的出来通过变量 id可以访问不同的用户信息。
- 不会暴露服务端架构的 URI。
api.sample.com/servlet/login.do 这样的代码傻子都知道后端是用面向环境编程的语言写的。
- 规则统一的 URI。
api.com.cn/Api/user-InfoById/info.json
- 当端点里出现两个以上的单词时，使用脊柱法（连词符号）。
api.linkedin.com/v1/people-search
本篇文章大部分读者都是工程师，而且很聪明。所以我认为没有必要对所有的特点进行说明。只要把以上特点都背下来然后记在脑子里，设计的第一步你就合格了。
合理利用 REST API
好的 WEB API 离不开的概念就是 REST API。那么优雅的 API 是不是一定要采用 REST API 来设计呢？
要理清这个问题首先要搞明白 REST 的准确含义到底是什么。
REST API 的概念首先出现在 Roy Fielding 的论文中。
狭义上的 REST API 实际上就是指符合 Fielding 的 REST 架构风格的 Web 服务系统。REST API 的设计风格严谨，考虑周全，结构优美。但过于苛刻的标准一直是狭义 REST API 推广壮大的绊脚石。
广义上的 REST API 指符合 RPC 风格的 JSON + Http 的接口的系统。这样的 REST API 定义却又过于粗犷和随意了。
于是，针对 WEB API 的发展以及广义 REST 与 狭义 REST 的特点， Martin Fowler 提出在达到完美的 REST API 之前有以下几种 API 的设计级别。
- REST LEVEL0: 使用 HTTP
- REST LEVEL1: 引入资源的概念
- REST LEVEL2: 引入 HTTP 动词
- REST LEVEL3: 引入 HATEOAS 概念
按照 HTTP 协议中，URI 代表资源，而 HTTP method 代表对资源的操作。
我以此理论作为基础，再参照上述 REST LEVEL，我设计了一个符合 REST LEVEL2 标准的示例 URI ，如下所示
| 目的 | 端点 | 方法
| -- | -- |
| 获取用户信息列表 | api.example.com/v1/users | GET |
| 新用户注册| api.example.com/v1/users | POST |
| 获取特定用户信息 | api.example.com/v1/users/:id | GET |
| 更新用户信息 | api.example.com/v1/users/:id/ |PUT/PATCH |
| 删除用户信息 | api.example.com/v1/users/:id | DELETE |
从今以后，你的 WEB API 只要参照以上示例设计，那就是符合基本标准，也很难被吐槽的 WEB API。
最后补充一点，虽然 REST Level3 描绘了一副美妙的蓝图。但截止本篇文章发表之前互联网上的大部分项目都只是朝向 Level2 的标准在努力，距离 LEVEL3 还有十分遥远的距离。故本篇文章就不在此展开对 LEVEL3 的讨论了。如果你有兴趣请自行参考相关资料了解。
总结
本篇文章是本系列的第一个篇章。着重围绕各大厂的 API 示例与设计行业的通用理念，归纳总结了若干设计国际范儿 api 的套路与规则。熟读这些套路，遵守这些规则是你领会 web api 设计的一小步。后期的文章中我们将逐步介绍各种设计细节，完善你的网络应用程序接口。
Copyright 2017/08/15 by Chuck Lin
参考书籍
《Web Api 的设计与开发》
