通过添加标头或正文参数，添加指令“如何"执行REST API请求? [英] Add instruction 'how' to perform a REST API request by adding header or body param?

问题描述

想象一个简单的REST API，它可以通过将JSON资源发送到POST /users来创建用户帐户，如下所示.默认情况下，它会向用户发送一封确认电子邮件.

Imagine a simple REST API that allows to create a user account, by sending a JSON resource to POST /users as in the following. By default it sends out a confirmation email to the user.

{
   "username": "[e-mail]",
   "password": "secret"
}

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

However sometimes there are good reasons for not sending out a confirmation based on the use case, e.g. another API client, or admins signing up users on their behalf.

由于它对创建的资源没有任何影响，但是更多地是关于如何创建用户的指令，因此它应该与请求主体分开吗?最好的方法是什么?

Since it doesn't have any implications on the created resource but is more of an instruction how to create the user, should it be separate from the request body? What's the best way to do this?

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

1. Specify a custom header Confirmation: no-confirmation
2. Add a query param ?confirmation=false
3. Add a send_confirmation field to the request body

推荐答案

让我们按顺序进行选择:

Let's take the options in order:

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

1. Adding a header value to indicate some semantic difference should be generally avoided. The API should be "browseable", meaning it should be discoverable following links only.

从REST的角度来看，添加查询参数完全等同于创建另一个URI.公开它的方式并不重要，关键是客户端需要遵循先前状态"链接中的某些链接.其实没关系，只要指向这些资源的链接指示您描述的不同语义即可:例如通过admin创建用户，创建自己的用户等.

Adding a query parameter is, from REST perspective completely equal to creating another URI. It does not really matter how you expose it, the point is that the client needs to follow some links from the previous "state" it was in. This is actually ok, as long as the links to these resources indicate the different semantics you described: like creating users by admin, users creating themselves, etc.

还请注意，API不一定必须公开是否发送确认. API应该公开目的"，然后服务器可以决定用例是否需要确认电子邮件.

Also note, that the API should not necessarily expose whether a confirmation is sent. The API should expose the "purpose", the server then can decide whether the use-case warrants a confirmation email.

在JSON表示形式本身中放入send_confirmation.如果这是用户可用的功能，则可以.例如，我可以询问以获取确认电子邮件.如果不能，并且仅用于区分不同的用例，那么我宁愿选择选项2.

Putting a send_confirmation in the JSON representation itself. This is ok, if this is a functionality available for the user. For example I can ask for a confirmation email. If I can't, and it is only used for differentiating different use-cases, then I would rather prefer option 2.

摘要:对于您所描述的情况，我将选择选项2:为管理员和普通用户提供不同的资源.

Summary: For the case you are describing I would pick option 2: different resources for admins and normal users.

这篇关于通过添加标头或正文参数，添加指令“如何"执行REST API请求?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！