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

【问题标题】：REST API Designing Endpoints (Action/Verb => Noun/Resource )REST API 设计端点（动作/动词 => 名词/资源）
【发布时间】：2017-10-11 00:16:08
【问题描述】：

根据设计REST API端点的this guide，我们不应该在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 消费者的角度来看，这似乎并不直观。请指导我在这种情况下应该如何进行。

【问题讨论】：

标签： rest api resources httpverbs

【解决方案1】：

根据这个设计 REST API 端点的指南，我们不应该在 URL 中使用动作/动词

REST 不在乎您对标识符使用什么拼写。这是重点的一部分。 /e25928c5-7b4e-44b8-be83-24ed9c9f8d3b 是一个完美的标识符。

Stefan Tilkov 对此进行了很好的讨论。

请指导我在这种情况下应该如何进行。

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

这就是 REST。

所以您正在寻找的名词是您用于导航更改主题协议的集成域中的名词；换句话说，它们是表单，以及表单提交收件箱。

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

你想要的思维导图不是动作（这太粗体了），而是请求——你正在发送消息询问某人else 采取您需要的操作。实际行动是副作用。所以“表单提交收件箱”是待处理的“更改主题”请求的集合。

使用任何当地的拼写约定来处理这类事情。

不要认为资源代表您的领域；资源支持您的集成协议，并且资源的名称取自您的集成域的语言，而不是您的业务域的语言。

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

【讨论】：

【解决方案2】：

PUT /themes/:name

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

【讨论】：

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

【解决方案3】：

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

我想创建另一个端点，通过它我可以执行操作（即切换主题），此操作将更改 DB 中设置表中的 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。

【讨论】：