这个REST API是否正确设计？

我正在开发部署系统，需要在池中的全部或部分机器上的池上部署一些应用程序。为了简单起见，可以说我对api只有3个要求。这个REST API是否正确设计？

部署
取消
状态

我现在感到困惑的设计为上述行动的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似乎并不正确。这是一个很好的设计吗？我已经在网上阅读了很多关于在REST中映射操作的文章，这些文章只会增加我的困惑。我的申请中没有任何CRUD。我只是想确保我以正确的方式做到这一点。有人能指出设计中的缺陷吗？任何指针都会有帮助。

来源

2013-10-06 Vaibhav Desai

我看不错！ –

我会删除网址中的“/ api”部分，但其余部分看起来不错。 – Farid

谢谢你的评论。 –

一对夫妇的想法：

首先，你的回应不允许的可能性，一些机器工作，有的机器则没有。所以你的响应可能需要是一个数组，每个尝试机器都有一个状态。

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

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

PUT to /myendpoint/api/job

带有包含池名称和机器数组的负载。响应将是一个状态和工作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到具有“取消”有效载荷的相同URL以取消作业。

来源

2013-10-06 07:20:04 djna

+1，除了PUT的语义在这里不合适 - PUT应该在PUTted的URL上创建一个新资源。使用POST。 –

@djna非常感谢。你把我放在正确的轨道上。关于你对每台机器状态的观察，我同意。我应该提到部署只是创建一个Quartz拾取的新工作。有关作业执行的所有细节将在状态调用中返回给客户端。 –

@AntonTykhyy是的，我将使用POST。我相信我不需要公开PUT，因为一旦创建了一份工作，没有什么可以改变。它只能被取消或查询状态。 –

对于取消和状态，我会更喜欢以下

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

我的设计将不承担空请求有效载荷的任何行动。这是为了防止非认真的用户不必要地攻击API。我期望一个有效载荷，否则向他们发出一个错误响应。

再次成功取消/状态，将发回像

响应

<?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>

来源

2014-06-04 00:43:45 Rockoder

这个REST API是否正确设计？

回答

相关问题