细粒度与粗粒度 REST API

Question

我正在开发用于管理用户的 REST API。每个用户都有名字和姓氏以及他自己的联系人列表（名称、类型、值）。我正在考虑两种对 REST API 进行建模的方法，即粗粒度方法：

• GET /user/{id}，获取用户详细信息及其联系人
• POST /users，添加新用户及其联系人
• PUT /users/{id}，更新用户及其联系人

或细粒度方法：

• GET /user/{id}，获取用户详细信息
• GET /user/{id}/contacts，获取用户的联系人
• POST /user，添加新用户
• PUT /user/{id}，更新用户
• POST /user/{id}/contacts，添加新的用户联系人
• PUT /user/{id}/contact/{id}，更新用户联系人
• DELETE /user/{id}/contact/{id}，删除用户联系人

什么时候应该选择细粒度方法而不是粗粒度方法？

Answer 1

这个决定取决于您的 API 的使用方式。如果此 API 的主要功能是跟踪用户的联系人，那么我认为采用细粒度方法是有意义的。

作为 API 的使用者，细粒度方法具有与粗粒度方法相同的功能，但还添加了更具体的端点。这样想，作为后端开发人员，您知道联系人嵌套在用户对象内，但 API 的使用者不知道这一点，也不需要知道这一点。他们只知道用户与其联系人之间存在某种关系。

此外，细粒度的方法将使您的后端代码保持井井有条。您将为 API 提供的每个端点提供特定的方法，因此代码将更易于阅读和理解。您还可以进行更细粒度和更干净的错误处理。