REST API 设计：请求特定参数

Posted 2023-02-16

【中文标题】REST API 设计：请求特定参数

【英文标题】：REST API design: request specific parameters

【发布时间】：2015-09-02 13:20:25

【问题描述】：

我们有一个 CORS REST API。它很干净。有用。这几乎是完美的。但是……

我正在尝试使用特定于请求的参数来实现端点。此端点应接受 POST、PUT、LINK 和 DELETE 请求。而且我不确定如何实现这些参数。

一个例子： 用户想要删除模型。有两种情况：一种是模型被删除，没有其他任何事情发生，另一种是模型被删除+发送通知电子邮件。

最初我在一个名为“X-NOTIFY-OWNER”的头文件中实现了这个参数。这很有效，因为它可以添加到 4 个动作中的任何一个中。但是现在我们想去掉那个标头，因为它对于这个单一的端点来说太具体了。

放置此参数的最佳位置是什么？查询参数听起来最干净（因为 DELETE 和 LINK 在技术上不需要正文），但查询参数应该用于过滤内容。请求正文中的参数也可以工作，并且似乎是首选方法；但这意味着发送带有 DELETE 和 LINK 操作的正文...

对这种情况下的最佳实践有什么想法吗？

【问题讨论】：

X-NOTIFY-OWNER 是请求头还是响应头？

这是一个请求头

说实话，我还是最喜欢header解决方案的。该参数特定于请求。有谁知道做类似事情的其他 api 的任何例子？

如果你还喜欢它，为什么要改变呢？您说查询字符串参数用于内容过滤，因此请继续使用它进行内容过滤。使用 X- 标头对我来说似乎又好又干净，我怀疑你能得到比这更有意义或更容易的任何东西。 IMO，使用自定义标头通知应用程序需要执行的额外任务是有意义的。

【参考方案1】：

我会坚持使用查询字符串，DELETE 应该忽略正文并仅读取 URL，因此在这里使用查询字符串是有意义的。

【参考方案2】：

您应该使用 URL 参数。正如您所说，它们应该用于过滤输出，并且可以将电子邮件视为输出。

【参考方案3】：

我建议为最干净的解决方案设置一个新端点。

example.com/endpoint

example.com/endpointAndNotify

你可以：

设置通知端点以扩展基本端点，然后将通知逻辑添加到通知操作。

从两个动作中抽象出共享逻辑，更新每个动作以扩展基类，然后在通知动作中添加具体的通知逻辑

这样两个端点都保持简洁明了，如果您为此端点定义一个标准，任何其他需要通知逻辑的端点都可以使用相同的标准。

【讨论】：

我们的端点是模型名称（名词）；这样就变成了：DELETE /meetings/id 和 DELETE /meetingsWithNotify/id。看起来不是一个干净的解决方案。