這個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是否正確設計？

回答

相關問題