REST API 设计端点( Action /动词 => 名词/资源)

Question

根据 this guide在设计 REST API 端点时，我们不应该在 URL 中使用 Action /动词(例如 /addNewEmployee)，如果我们想执行一个 Action ，我们应该只使用带有相应资源/名词的 HTTP 动词(例如 POST/employees).

现在，我有一个名为 themes 的资源，我围绕它创建了以下端点:

GET/themes(列出所有主题)

GET/themes/:name(列出具有给定名称的单个主题)

我想创建另一个端点，通过它我可以执行一个操作(即切换主题)，这个操作将更改数据库中 Settings 表中的 current_theme 字段值。我不确定这样做的最佳实践是 REST API 时尚，而且对消费者来说也是直观的。

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

Answer 1

According to this guide of designing REST API endpoints, we should never use action/verbs in URL

REST 不关心您使用什么拼写作为标识符。这是重点的一部分。 /e25928c5-7b4e-44b8-be83-24ed9c9f8d3b 是一个完美的精细标识符。

Stefan Tilkov对此进行了非常好的演讲。

Please guide me how should I proceed in such scenario.

想想您将如何使用网站。你会在某个页面上有一堆链接，其中一个链接上有一个标签，比如 changeTheme。您将单击该链接，并看到一个包含表单的新页面，其中包含可用主题列表。您将从列表中选择您想要的主题，然后提交表格。该请求将转到后端，更新一些资源。 副作用，您的主题记录将被更改。您可能会收到一条消息，告诉您已进行更改，并将您重定向回开始的位置。

这就是 REST。

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

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

您想要的心理映射不是 Action (这太大胆了)，而是请求——您正在发送消息询问其他人 采取您需要的行动。实际作用是副作用。所以“表单提交收件箱”是待处理的“更改主题”请求的集合。

对于此类事情，请使用本地的拼写约定。

远离资源代表您的域的想法；资源支持您的集成协议(protocol)，并且资源的名称取自您的集成领域的语言，而不是您的业务领域的语言。

POST使用 unsafe semantics 发送请求几乎总是一个可接受的选择到服务器。请记住，我们在这里是因为网络有效，从a media type开始仅支持 GET 和 POST。