什么是好的 Web Api

PS：本系列文章，是将 让 Java 再次伟大 产品中的设计哲学进行提取，再加工后输出的内容。

web api 就像一张名片一样，专业的名片可以迅速帮助你与客户之间建立信任感，也可能让你的产品在被使用前，就给客户留下业余，糟糕的负面印象。而一旦客户对你的产品产生负面情绪，这种情绪就会蔓延到产品生态圈甚至于相关公司上。

什么是优雅的 Web Api

类似设计模式的精髓在于设计原则，而非模式的生搬硬套一样，优雅的 Web Api 有两个重要原则：

• 设计规范明确的内容必须遵守相关规范
• 没有设计规范的内容必须遵守相关事实标准

给自己一些时间，认真阅读并体会上面两个重要原则。

厂名	uri	备注
Twitter	api.twitter.com/1.1	“治国理政平台”
Google Calendar	www.googleapis.com/calendar/v3	“大厂”
instagram	api.instagram.com/v1/usrs/search?q=jack	“宠物自拍网站”
linkedin	api.linkedin.com/v1/people-search	“招工”
Tumblr	api.tumblr.com/v2	“汤不乐”
foursquare	api.foursquare.com/v2/venues/search?q=apple&categoryId=asad123456	“基于地理位置社交”

如何设计出国际范儿的 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 与 狭义 REST 的特点， Martin Fowler 提出在达到完美的 REST API 之前有以下几种 API 的设计级别。

• REST LEVEL0: 使用 HTTP
• REST LEVEL1: 引入资源的概念
• REST LEVEL2: 引入 HTTP 动词
• REST LEVEL3: 引入 HATEOAS 概念

以此理论作为基础，再参照上述 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。