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

Question

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

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

将 Action 重构为看起来像资源的字段，例如如果您的操作是激活引擎，请设计 URI:PATCH engines/123 , 正文:{"status":"active"}

将 Action 视为子资源，例如PUT engines/123/active没有 body

使用查询参数，例如PUT engines/123?activate=true

务实，使用非 RESTful、RPC 风格的 URL，例如PUT engines/activate?id=123

我绝对装不下 deploy/ undeploy/ execute按照#1 和#2 中的建议对资源进行编码操作。您能否分享您的意见，我们如何才能最好地为这些操作设计 API？

Answer 1

Could you please share your opinion how best we can design the APIs for these actions?

创建/更新/删除信息资源，并作为其副作用，在 API 后面工作。
所以想想文档。
一个很好的例子:在 RESTful Causistry ，Tim Bray 询问了关闭机器的 api。 Seth Ladd's response ，尤其是阅读
从根本上说，REST 是一种解决文书工作问题的官僚机构。如果您想完成任何事情，请提交正确的表格；它成为描述您想要完成的工作的信息资源。

PUT /deploymentRequests/abcde

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

201 Created

请求只是一份文件，与您办公 table 上要求您处理某项任务的便签完全相同，它也是一份文件。
就 REST 而言，URI 的拼写绝对无关紧要；但从人类可读的命名约定的角度来看，从资源就是文档这一事实开始——而不是您希望文档具有的副作用。
因此，例如，描述事物当前状态的文档和描述您想要对事物进行更改的文档是具有不同标识符的不同文档，这是完全正常且符合 REST 的。