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

Question

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

{
   "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. 在JSON表示中放置send_confirmation。如果这是用户可用的功能，这是可以的。例如，我可以询问以获取确认电子邮件。如果我不能，并且它仅用于区分不同的用例，那么我宁愿选择选项2.

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