细粒度与粗粒度 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 提供的每个端点提供特定方法，因此代码将更易于阅读和理解。您还可以获得更细粒度和更干净的错误处理。