设计 API 时,是按照业务场景还是按照资源拆分?

Question

我又一个 users 表,表中有 vendor / photography / editor 等几种不同的角色. 使用字段 type 来区分. 但是其中 vendor 类型的 users, 每个 vendor 又可能有多个 vendor_category.

现在有个地方需要搜索符合条件的 vendor list. 要把 vendor_category 也返回.

那么我是

提供一个   GET /users api ,通过传递 的 type 来限定为 vendor ,并且加上   vendor_category 信息.

还是:

提供一个  GET /vendor api, 只处理 vendor 的信息.

Answer 1

一般还是按业务的restful接口规范，像graphql这种按资源也可以用

Answer 2

你要考虑这个业务所涉及的场景的主要元素是什么。

需要搜索符合条件的 vendor list. 要把 vendor_category 也返回.

你这里既然 vendor 都已经是主语了，没有涉及到 users ，为什么还要去想 users 的事儿？

如果是 **搜索符合 vendor 的 users ，且要 vendor_category 。那么你这里就可以用 users 作为主语，在Restful 设计中，除开关系外，过滤都是应该采用 查询字符串来解决。

而且，不要把一个接口的数据返回结果可能性和传递参数设置太多，这样会增加以后维护的难度。业务运行后也会难免有一些不可预见的bug。