优秀的 REST API 设计指南

2020-07-29 06:14:50 +08:00
 KalaSearch

这是一篇会长期更新的文章

什么样的 API 设计能被称为优秀当然是一个非常主观的标准,但是还是有一些客观可考量 API 质量的数据,比如

  1. 接了你设计的 API 的前端给好评的比例是多少,还是边接边骂
  2. 如果你的 API 本身就是你的产品的话(比如 Stripe,Algolia 或者 Github 等等),你的用户会对你的 API 好评吗
  3. API 是不是一读即可以清晰地知道,对应接口是做什么的。换句话说,接入 API 时需要的交流时间成本有多高

不管是前端程序员还是后端程序员,都少不了跟 API 打交道。后端需要把 API 设计和实现出来,而前端程序员需要把界面逻辑和 API 接起来,因此对于 REST 的设计规则有一些基本了解,不管你是前端还是后端,都会有很大帮助。

之前在厂里设计了一些还算被广泛使用的 API, 因此我写了这篇文章,结合之前的经验总结了一些要点。希望作为一个参考,可以帮助大家

文章请戳 => 优秀的 REST API 设计指南

当然我想要说明的是,设计 API 在一定范围内是有规律可循的,但是太过抠细节则会陷入无穷无尽地“宗教版”争论中,所以请大家理论讨论。

你们设计 API 的时候有些什么原则?有哪些好的规范和经验可以介绍和分享给大家?欢迎告诉我,我会加到文章中

26083 次点击
所在节点    程序员
98 条回复
KalaSearch
2020-07-29 06:15:36 +08:00
abbycin
2020-07-29 07:24:49 +08:00
我八股文写得特别好
baiyi
2020-07-29 07:30:25 +08:00
我认为在设计过程中,需要考虑 HTTP 方法的幂等性。比如 Github 的 Star 操作,为什么是 PUT 而不是 POST,就是从幂等性方面考虑的
KallyDev
2020-07-29 07:31:05 +08:00
补充一个微软在 GitHub 公开的规范,非常详细

https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md
shijianit
2020-07-29 08:21:40 +08:00
如果要接口全部加密,get 方式请求,不是会暴露出来 id 数据吗?
xuanbg
2020-07-29 08:22:37 +08:00
修改密码和重置密码怎么设计?软删和硬删同时存在怎么办?
xuanbg
2020-07-29 08:23:09 +08:00
@shijianit 所以 id 不要用自增
bsg1992
2020-07-29 08:43:48 +08:00
这种只适合对外的 api 并且功能单一
一个 ERP 查询几十个字段你用 get?
gnozix
2020-07-29 08:51:17 +08:00
想问问下载接口应该怎么设计
gowk
2020-07-29 09:08:48 +08:00
@bsg1992 人家说的是在卡拉搜索的业务背景下,设计优秀 API 的最佳实践,你非要拿 ERP 来杠,有意思么
nockyQ
2020-07-29 09:12:50 +08:00
关于版本划分这一块,除了常见的 URI 版本控制之外还有其他两种。
https://restfulapi.net/versioning/
感觉楼主可以在这个基础上展开聊一聊。
lolizeppelin
2020-07-29 09:36:29 +08:00
paypal api 和沙箱比微信支付漂亮太多了

但是不妨碍 paypal 垃圾微信支付好用......
KalaSearch
2020-07-29 09:46:01 +08:00
@nockyQ 啊是的,stripe 用的是这种。感谢你的新信息
KalaSearch
2020-07-29 09:46:30 +08:00
@baiyi 感谢 <3
KalaSearch
2020-07-29 09:46:48 +08:00
@KallyDev 这个很赞,我之前也看过,谢谢提出来,我会加到文章里
KalaSearch
2020-07-29 09:47:56 +08:00
@shijianit id 应该默认认为已经暴露,藏不住。楼下说的用 uuid 是个好办法,不过不管怎么样不应该认为 id 可以隐藏起来达到安全的目的。(安全我懂得不多,更详细等楼下们讨论啦)
KalaSearch
2020-07-29 09:48:35 +08:00
@gnozix 能说说具体场景吗?文件下载?
wellsc
2020-07-29 09:53:32 +08:00
restfool (逃
MrTreasure
2020-07-29 10:25:34 +08:00
还是缺乏具体场景,文中的内容就是是属于 restful 的标准。但是对于难点没有很好的讲解,比如 restful 如何返回错误。区分 HTTP 错误以及业务错误
ZacksT
2020-07-29 10:58:18 +08:00
你的 REST API 满足公司 /研发团队标准就是好的设计。接口标准可以帮助开发者规避(公司研发 /团队研发)遇见过的问题或可能遇到的问题,也可以让组内代码标准化,统一化。

就拿一个简单的例子,一个分页查询的接口。其包含分页条件与不定量的查询条件。
你可以通过 GET 方式请求,将参数定义在 url 上。也可以通过 POST 方式请求,将查询参数定义在 requestbody 里。
第一个方式,在遇到查询条件复杂的情况下,会导致 url 过长。
第二种方式,又会产生很多 VO 的定义。
采用混搭又让前后端代码变得混乱。

我个人认为,只要满足团队要求的 API,就是好的 API 。具体实现各有好处,看团队取舍了

这是一个专为移动设备优化的页面(即为了让你能够在 Google 搜索结果里秒开这个页面),如果你希望参与 V2EX 社区的讨论,你可以继续到 V2EX 上打开本讨论主题的完整版本。

https://www.v2ex.com/t/693907

V2EX 是创意工作者们的社区,是一个分享自己正在做的有趣事物、交流想法,可以遇见新朋友甚至新机会的地方。

V2EX is a community of developers, designers and creative people.

© 2021 V2EX