问题描述
我有多台服务器,并且正在构建一个应用程序来控制它们,检查其状态等。我想创建一个端点来允许我打开/关闭服务器,但是,我不确定如何正确设计REST API。
当前,假设我有一个Server
资源,控制它的端点是/api/servers/{id}/start
和/api/server/{id}/stop
。只需发送一个空的POST请求即可打开和关闭服务器,即可使用它们。
这很好,但是我不确定这是否是API的简洁设计。我找不到有关此主题的任何建议。
谢谢!
解决方法
这很好,但是我不确定这是否是API的简洁设计。我找不到有关此主题的任何建议。
这是 fine ,但可能会更好。
简短版本:与其在特定资源上发布空消息,不如在您希望更改的资源上发布详细消息。
长版本:每当您试图弄清楚在REST中做什么时,正确的出发点就是考虑如何处理普通的旧网页。
在网络上,您将打开一个包含不同服务器列表的页面。这些服务器中的每一个可能都具有某种状态指示器,以及可能要进行的每个更改的链接。单击该链接将带您到一个表单,该表单可能已预先填充了数据。您将更改任何必要的默认值,然后提交表单,浏览器将创建HTTP请求,该请求告诉Web服务器重新启动服务器#7,或进行其他操作。塔达。
请注意,浏览器和人类都无需事先知道要使用哪个URI,因为该信息包含在网页的表示中。浏览器需要知道链接如何工作以及表单如何工作。人们需要知道要遵循的 链接,以及如何解释表单中的输入控件,但是由服务器来决定什么是标识符以及应使用哪些键/值对在请求正文中,依此类推。
鉴于此,您如何确定表单操作的目标?一种可能的答案是考虑缓存的含义。 RFC 7234表示,成功的POST将invalidate目标uri的所有缓存表示形式。因此,如果将请求发布到希望被请求更改的网页上,那么您将获得“免费”的适当缓存行为。
高速缓存失效规则不灵活-它们旨在支持常见情况。如果您有许多要通过请求更改的缓存页面,则需要选择其中一个页面对更新最重要。
将这些想法与您的情况相匹配:可能是您的表单更改的最重要的文档是/api/servers/{id}
,因此该文档应成为表单提交的目标
POST /api/servers/1
Content-Type: text/plain
STOP
POST /api/servers/1
Content-Type: text/plain
START