通过添加标头或正文参数添加指令“如何”执行 REST API 请求？

Question

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

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

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

既然它对创建的资源没有任何影响，而是更多地说明如何创建用户，它是否应该与请求正文分开？最好的方法是什么？

1. 指定自定义标头Confirmation: no-confirmation
2. 添加查询参数?confirmation=false
3. 在请求正文中添加 send_confirmation 字段

Answer 1

让我们按顺序选择选项：

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

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

   另请注意，API 不一定要公开是否发送了确认。 API 应该公开“目的”，然后服务器可以决定用例是否需要确认电子邮件。

3. 将send_confirmation 放入 JSON 表示本身。没关系，如果这是用户可用的功能。例如，我可以要求确认电子邮件。如果我不能，并且它仅用于区分不同的用例，那么我宁愿选择选项 2。

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