需要多个不同资源的 REST API？

Posted 2023-02-19

【中文标题】需要多个不同资源的 REST API？

【英文标题】：REST API which needs multiple different resources?

【发布时间】：2021-12-30 18:00:42

【问题描述】：

我正在设计一个 REST api，用于在不同域的虚拟机上运行作业（Active Directory 域，同名的虚拟机可以存在于不同的域中）。

/domains
/domains/dname
/domains/dname/vms
/domains/dname/vms/cname

对于将存储在数据库中的作业

/jobs
/jobs/id

现在我需要为以下用户故事添加新的 API。

作为用户，我想在现有 VM 上运行作业（只是作业定义，而不是存储的作业）。 作为用户，我想在名为 x 的 VM 上运行一个作业（只是作业定义，而不是存储的作业），它可能存在也可能不存在。如果x 不存在，系统应该创建虚拟机。

api应该如何设计？

方法一：

PUT /domains/dname 
 "state": "running_job", "vm": "vm_name", "job_definition":  ....  

方法2：

PUT /domains/dname/vms/vm_name
 "state": "running_job", "job_definition":  ....  

方法 3：

PUT /jobs
 "state": "running", "domain": "name", "vm": "vm_name", "job_definition":  ....  

方法4：创建一个新资源，说调度器，

PUT /scheduler
 "domain": "name", "vm": "vm_name", "job_definition":  ....  

（如果我以后需要更新调度器的某些属性怎么办？）

一般来说，如何设计需要多个资源的 REST API url？

【问题讨论】：

/jobs 不适合，因为它用于存储作业。你没有告诉 /domains 实际上做了什么。也许合适，也许不合适

更新了问题 - "domain": "name" 添加到方法 3 和 4。域是 Active Directory 域。

【参考方案1】：

api应该如何设计？

你会如何在网络上设计这个？

会有一个 html 表单，对吧？使用一堆输入控件从操作员那里收集有关要使用什么作业以及要定位哪个 VM 等信息。操作员将填写详细信息，提交表格。然后浏览器将使用表单创建适当的 HTTP 请求以发送到服务器（请求目标是根据表单元数据计算的）。

由于服务器可以决定请求目标应该是什么（使用hypertext 的好处），它可以选择它想要的任何资源标识符。在 HTTP 中，一个成功的不安全请求恰好会使先前缓存的具有相同请求目标的响应失效，因此一种可能的策略是考虑哪个是通过成功处理请求而更改的最重要的资源，并将该资源用作目标。

在这种特定情况下，我们可能有一个代表作业队列的资源（例如 /jobs），而我们在这里所做的是在队列中提交一个新条目，所以我们可能期望

POST /jobs HTTP/1.1
....

如果服务器在处理请求时也为特定作业创建新资源，那么这些将在响应中指示

HTTP/1.1 201 Created
Location: /jobs/931a8a02-1a87-485a-ba5b-dd6ee716c0ef
....

---

你能改用 PUT 吗？

PUT  /jobs/931a8a02-1a87-485a-ba5b-dd6ee716c0ef HTTP/1.1

???

是的，如果 (a) 客户端知道请求目标使用什么拼写并且 (b) 客户端知道资源的表示应该是什么样子。

您在触发业务活动的消息中使用哪种不安全的 HTTP 方法实际上并不重要。您需要正确使用这些方法（以免通用 HTTP 连接器被误导）。

特别要记住关于 PUT 的重要一点是请求主体应该是资源的完整表示 - 换句话说，PUT 的请求主体应该与 GET 的响应主体匹配。想想“保存文件”；我们对资源副本进行了本地编辑，并将整个文档的副本发回。

【讨论】：

我认为我应该在所有示例中使用 PATCH。