REST API设计端点（动作/动词=>名词/资源）

Question

根据设计REST API端点的指南，我们不应该在URL中使用动作/动词（如/addNewEmployee），如果要执行操作，只能使用带有相应资源/名词的HTTP动词（例如POST /employees）。

现在，我有一个名为themes的资源，我已经围绕它创建了以下端点： GET /themes（列出所有主题） GET /themes/:name （按给定名称列出单个主题）

我想创建另一个端点，通过它可以执行一个操作（即切换主题），此操作将更改DB中 Settings 表中的current_theme字段值。 我不确定在REST API风格下应采用什么最佳实践，并且对于用户来说也很直观。

我可以这样做POST /themes/changeTheme或PUT /themes/:name/activate，但是changeTheme和activate都是动词。 我也可以这样做PUT /settings，但从API使用者的角度来看，这似乎不太直观。 请指导我如何在这种情况下继续进行。

- Faisal Khurshid

Answer 1

我知道这是一个老问题，但我想在此添加一些内容。

我想创建另一个端点，通过它可以执行一个操作（即切换主题），此操作将更改DB中Settings表中的current_theme字段值。 我不确定以REST API方式执行此操作的最佳实践，并且对于消费者来说也直观易懂。

如果您仔细阅读加粗部分，它会更改Settings资源中的某些内容（current_theme），而不是Theme本身。 在我的看法中，Theme不应该关心它是否是active主题。

考虑到这一点，我会设计如下：

PUT /settings/current-theme
{"themeId": "<some-id>"}

我认为这已经很直观了。

• PUT 表示更新操作，
• /settings/current-theme 表示更新 Settings 资源的 currentTheme 属性，以及
• Body 提供属性的新值。

当然，如果你从其他资源池中选择资源，则可以使用 PUT /settings/:id/current-theme。

- Sasho Najdov

Answer 2

根据设计REST API端点的指南，我们不应该在URL中使用动作/动词。 REST并不关心您为标识符使用什么拼写。这是其中一部分的要点。 "/e25928c5-7b4e-44b8-be83-24ed9c9f8d3b" 是一个完美的标识符。 Stefan Tilkov做了一次非常好的演讲，请参考。请指导我在这种情况下应该如何继续。

思考一下如何在一个网站上实现。你将会在某个页面上，有许多链接，其中一个链接的标签可能是changeTheme。你会点击该链接，然后进入一个新页面，包含一个表单，列出可用主题的列表。你会从列表中选择你想要的主题，并提交表单。该请求将会发送到后台，更新某些资源。作为副作用，你的主题记录将被更改。你可能会收到一条消息告诉你变更已经完成，并将你重定向回原来的页面。

这就是REST。

因此，你要寻找的名词是集成域中用于导航更改主题协议的名词；换句话说，它们是表单和表单提交收件箱。

Jim Webber将Web的模型描述为1950年代办公室的模型；通过检索表单、填写表单并将其放入收件箱来完成工作。

你需要的是一种心理映射，不是一个“动作”（太大胆了），而是一个“请求”，你正在发送一条消息，要求某个人承担你需要的行动。实际行动是副作用。因此，“表单提交收件箱”是未决“更改主题”请求的集合。

使用当地的拼写约定。

避免认为资源是你的域的表示；资源支持你的集成协议，资源名称来自于你的集成域的语言，而不是你的业务域的语言。

使用POST几乎总是发送具有不安全语义的请求到服务器的可接受选择。记住，我们在这里是因为Web从支持仅GET和POST的媒体类型开始运行。

- VoiceOfUnreason

Answer 3

PUT /themes/:name

这意味着你将更改这个单一的主题。你可以传递一些属性并且只改变它们。

- rcmstark

---

PUT /themes/:name 也可以意味着更改主题本身。我建议将 PUT /active-theme/:name 和 PUT /themes/:name 作为不同的端点使用。 - egvo