添加指令 'how' 以通过添加 header 或 body 参数来执行 REST API 请求？

Add instruction 'how' to perform a REST API request by adding header or body param?

想象一个简单的 REST API 允许创建用户帐户，方法是将 JSON 资源发送到 POST /users，如下所示。默认情况下，它会向用户发送一封确认电子邮件。

{
   "username": "john@appleseed.com",
   "password": "secret"
}

然而，有时有充分的理由不根据用例发送确认，例如另一个 API 客户，或代表他们注册用户的管理员。

由于它对创建的资源没有任何影响，更多的是说明如何创建用户，是否应该将其与请求分开body？最好的方法是什么？

  1. 指定自定义 header Confirmation: no-confirmation
  2. 添加查询参数?confirmation=false
  3. 向请求中添加一个 send_confirmation 字段 body

让我们按顺序选择：

  1. 通常应避免添加 header 值来指示某些语义差异。 API 应该是“可浏览的”，这意味着它应该只能通过链接被发现。

  2. 从 REST 的角度来看，添加查询参数完全等同于创建另一个 URI。你如何公开它并不重要，关键是客户端需要从它所处的先前“状态”中跟踪一些链接。这实际上没问题，只要这些资源的链接表明你描述的不同语义: 比如管理员创建用户，用户自己创建等

    另请注意，API 不一定会显示是否已发送确认。 API 应该公开“目的”，然后服务器可以决定 use-case 是否需要确认电子邮件。

  3. 将 send_confirmation 放入 JSON 表示本身。这没关系，如果这是对用户可用的功能。例如，我可以询问 一封确认邮件。如果我不能，而且它只是用于区分不同的use-case，那么我宁愿选择选项2。

总结：对于您所描述的情况，我会选择选项 2：管理员和普通用户的不同资源。