Question

我正在开发一个部署系统，该系统需要在池中的所有或部分计算机上部署一些应用程序。为了简单起见，我可以说我对api只有3个要求。

部署
取消
状态

我现在很困惑为上面的操作设计REST api调用：这是我的想法。如果有效负载为空，我将部署在池中的所有计算机上。

http://my-endpoint/api/{pool-name}/deploy

Payload:
{
    "machines" : [
        "machine-1.fqdn",
        "machine-2.fqdn",
        "machine-3.fqdn"
    ]
}
Response:
{
    "status": "OK",
    "jobId": "9999"
}

然后，客户端可以根据jobId：

http://my-endpoint/api/{pool-name}/status/{jobId}
http://my-endpoint/api/{pool-name}/cancel/{jobId}

现在，jobId在整个部署系统中是唯一的，因此在“状态”和“取消”的api中使用{pool-name}似乎不正确。这是一个很好的设计吗？我在线阅读了很多关于在REST中映射操作的文章，它们只会增加我的困惑。我的申请中没有任何CRUD。我只想确保以正确的方式做到这一点。有人可以指出设计中的缺陷吗？任何指针都会有所帮助。

Answer 1

有几点想法：

首先，您的回复不允许某些机器工作而某些机器不工作。因此，您的响应可能需要是一个数组，每个尝试过的机器都有一个状态。

其次，这不是严格的安抚，你创建的URL是有效的动词。实际上它会起作用，但要成为RESTful，你应该识别你的实体并使用GET，PUT，POST和DELETE。

所以这里你的实体可能只是工作。

PUT to /myendpoint/api/job

使用包含poolname和机器数组的有效内容。响应将是一系列状态和工作ID。

[ 
{
"status": "OK",
"jobId": "m1-9999"
},{
"status": "OK",
"jobId": "m2-9999"
},{
"status": "BAD",
"machine": "m3"
"reason": "xxx"
}
]

您在工作ID上获取GET以获取状态。 jobid足以识别它所在的机器。

GET myendpoint/api/job/m2-9999

并使用“取消”的有效内容POST到相同的网址以取消作业。

Answer 2

对于取消和状态，我实际上更喜欢关注

http://my-endpoint/api/{pool-name}/cancel/{job-id}

我的设计是不对空请求有效负载采取任何操作。这是为了防止非严重用户不必要地攻击API。我希望有一个Payload，否则会向他们发回Error响应。

再次成功取消/状态，会发回一个像

这样的回复

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<request-result>
<http-code>200</http-code>
<description>REST Request is successfully processed</description>
<internal-error-info></internal-error-info>
<message>Job with {id} is processed successfully</message>
<requested-operation>Cancel</requested-operation>
<resource-name>JobName</resource-name>
<status>SUCCESSFUL</status>
</request-result>

这个REST api是否正确设计？

2 个答案: