如何最好地設計RESTful API以啟動操作

Question

我正在構建一個RESTful Web服務，它對一組數據類型具有通常的CRUD操作風格。 這些API的HTTP謂詞映射是顯而易見的。

有趣的部分來自客戶端可以請求初始化對其中一個數據對象的長時間運行（即小時）操作; 通過查詢數據類型本身來報告操作的狀態。

例如，假設一個具有以下特征的對象：

SomeDataType
{
    Name: "Some name",
    CurrentOperation: "LongOperationA",
    CurrentOperationPercent: 0.75,
    CurrentOperationEtaSeconds: 3600
}

那么，我的問題是啟動LongOperationA最好的RESTful方法是什么？

最明顯的方法似乎是將操作本身作為標識符，或許類似於POST https://my-web-service.com/api/StartLongOperationA?DataID=xxxx ，但這看起來有點笨重，甚至如果我沒有將數據標識符指定為查詢參數。

將此實現為冪等行為也是非常簡單的，因此使用POST似乎是浪費; 另一方面， PUT很笨拙，因為實際上沒有數據寫入服務。

有沒有其他人在他們的服務中遇到過這種情況？ 您如何使用API​​來初始化符合RESTful主體的操作？

TIA，

-標記

Answer 1

你可以這樣做，

POST /LongRunningOperations?DataId=xxxx

創建一個新的LongRunningOperation。 長時間運行操作的URI將在Location標頭中返回201狀態代碼。

或者，如果您希望保持與DataId關聯的長時間運行操作，則可以執行此操作

POST /Data/xxx/LongRunningOperations

這兩個選項都可以讓您查詢是否仍在執行長時間運行的操作。 如果您在操作完成后需要信息，則可以創建類似的內容

GET /CompletedLongRunningOperations
GET /Data/xxx/CompletedLongRunningOperations
GET /Data/xxx/LastCompletedLongRunningOperation