优秀的 REST API 设计指南

[KalaSearch]

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

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

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

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

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

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

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

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

[KalaSearch]

@ZacksT 感谢回复。是的，满足团队、客户需求就是好 API 。对于你说的参数定义的例子，GET + URL 参数挺好的，遵从 REST 语义



@wellsc 不要淘气

[bsg1992]

@gowk 我并没有杠，你说回复也印证了我上面说的 [适合对外的 api 并且功能单一] r

[ibreaker]

小伙子很活跃啊，天天都能刷到你

[lovedebug]

@ZacksT 分页 GET 查询一般只带 limit 和 page，少量支持投影和过滤，如果有带其他复杂的 query 条件，其实更应该走 POST search 自定义方法

[ieiayaobb]

Get by Id 的比较明确，如果是 Get by name 这种，name 是唯一的怎么设计比较好？不想用 query 是因为不想在 name 不存在的时候返回空数组，而是希望也能和 Get by id 一样返回 404

[xjchenhao]

修改密码和重置密码，逼死强迫症😂

[xjchenhao]

@xuanbg 修改密码和重置密码，逼死强迫症😂

[grzhan]

之前负责撰写公司的 API 规范，当时也参考了很多包括 Azure （ https://docs.microsoft.com/zh-cn/azure/architecture/best-practices/api-design ）、Google Cloud （ https://cloud.google.com/apis/design/ ）等公司的规范，大厂的标准往往更加规范，给人很多对于 API 设计上概念理解的启发。

其中感觉最详细的大概是 Zalendo 的： https://opensource.zalando.com/restful-api-guidelines/ ，其中有非常多的实践是可以参考的，也像 RFC 一样规范了 MUST 、SHOULD 、MAY 的遵守分级。

关于文中提到的 REST 表示一个动作，我们参考的更多是 ElasticSearch API 的做法，即将动词加上下划线前缀，作为 POST 方法进行服务，形如： http://cloud.sy/machine/xxxx/_restart

关于这一块 Google API 是用冒号作为前缀的，但一些路由框架会占用冒号作为关键字，因此考虑使用下划线代替。

[gnozix]

@KalaSearch 对前台展示的表格数据，以 excel 的格式进行下载；所以需要下载的比较多。感觉 REST 风格不太容易表示需要下载的资源

[wshcdr]

值得看一下

[Heanes]

同意 8 楼，系统内部交互可能还是“常规”的设计形式

[lovedebug]

@grzhan 同负责撰写 API 规范，其实关于 list 操作的 filter 功能，在实际 API 设计中有些疑惑使用场景，因为大部分情况下使用一般的 query parameter 就可以解决。我的理解是一般的 query parameter 默认是 and 操作，缺乏 or 操作以及 range value 等功能，而 $filter 主要在 url 中描述若干参数复杂的逻辑运算，如果这么做用 POST 自定义动作不是更好吗？想听一下你的理解。

[xuanbg]

@lovedebug 要是支持复杂的 or 和 and 条件组合，url 参数就丑的要死了……不信的可以看 kibana

[szthanatos]

批量操作的实践为什么很少有人谈←_←

[solee]

经过几年的实践，我们最后全部统一了用 POST，之前看过一篇亚马逊写的关于 Restful API 设计的改进，加入动词的描述，感觉更合理

[lovedebug]

@szthanatos 微软规范有谈的

[lovedebug]

@xuanbg 哈哈 跟业务场景有关，如果不想用万能 POST，可能只能在 url query 中支持一些 or 查询，客户在使用我们的 public api 时提出的

[lovedebug]

@solee 自定义动词应该在已有的 RESTful 规范不满足时候才使用

[Nolink]

收藏了，谢谢分享

[ericls]

用现成的 query language 不好吗？ 非要把 http headers 滥用成 query 还要自己定义 实现 维护……