用于非 CRUD 操作的 REST API 设计，例如保存、部署、执行代码

Question

我的 REST API 上下文中的资源是用某种编程语言编写的应用程序代码。可以轻松映射到 HTTP 动词的 CRUD 操作是保存/编辑/删除代码。难以映射到 HTTP 方法的非 CRUD 操作是在服务器上部署代码、执行代码和取消部署。

我在 SO 中遇到的常见建议是：

1. 重构动作使其看起来像一个资源的字段，例如，如果您的动作是激活引擎，请设计 URI: PATCH engines/123, body:{"status":"active"}
2. 将动作视为子资源，例如PUT engines/123/active没有主体
3. 使用查询参数，例如 PUT engines/123?activate=true
4. 务实，使用非 RESTful、RPC 风格的 URL，例如 PUT engines/activate?id=123

我绝对不能够适应deploy/ undeploy/execute代码行动，以资源为＃1和＃2建议。您能否分享您的意见，我们如何才能最好地为这些操作设计 API？

Answer 1

我认为您正在寻找控制器，根据REST API 设计 RuleBook：

\n

\n

控制器资源对过程概念进行建模。\n控制器资源就像可执行函数，具有参数和返回值；输入和输出。\n与使用 HTML 表单的传统 Web 应用程序\xe2\x80\x99 一样，REST API 依赖于控制器资源来执行特定于应用程序的操作，这些操作无法在逻辑上映射到标准方法之一（创建、检索、更新和删除，也称为 CRUD）。\n控制器名称通常显示为 URI 路径中的最后一段，在层次结构中没有子资源跟随它们。\n下面的示例显示了允许客户端重新发送的控制器资源对用户的警告:\nPOST /alerts/245743/resend

\n

\n

并且：

\n

POST should be used to create a new resource within a collection and execute controllers.\n

\n

Answer 2

您能否分享您的意见，我们如何才能最好地为这些操作设计 API？

创建/更新/删除信息资源，并且作为其副作用，在 API 后面工作。

所以想想文档。

一个很好的例子：在RESTful Causistry 中，Tim Bray 询问了一个用于关闭机器的 api。 Seth Ladd 的回答尤其值得阅读

从根本上说，REST 是一种解决文书工作问题的官僚机构。如果您想完成任何事情，请提交正确的表格；它成为描述您想要完成的工作的信息资源。

PUT /deploymentRequests/abcde

Please find the artifacts from build 12345 and deploy that artifact
to machine 67890

201 Created

请求只是一份文件，与您办公桌上要求您处理某项任务的便签完全相同，它也是一份文件。

就 REST 而言，URI 的拼写绝对无关紧要；但从人类可读的命名约定的角度来看，从资源就是文档这一事实开始——而不是您希望文档具有的副作用。

因此，例如，描述事物当前状态的文档和描述您想要对事物进行更改的文档是具有不同标识符的不同文档，这是完全正常且符合 REST 的。