2015-04-26 48 views
1

我有一些用戶必須執行批准/拒絕工作流的資源。REST API中的交易

我遇到的問題是我需要在一個事務更新當前審批步驟並創建一個新的。所以我可以做以下幾點:

更新目前的審批步驟(用戶批准或拒絕後)

PUT myapi/approval_step/1 
{status: "approved"} // or status="rejected" 

然後創建下一個審批步驟:

POST myapi/approval_step/ 
{...} 

但我同時需要更新和創作一筆交易。

那麼,我如何解決這個問題,併爲我的情況構建優雅的REST API?

最容易讓我似乎只是爲了引進rejectapprove動詞,如:

POST myapi/approval_step/2/rejectPOST myapi/approval_step/2/approve這將更新現有的審批步驟,並創建新的,但設計REST API

時,應避免動詞
+0

類似於{'status':'approved','new':{...}}?不要以爲它看起來非常優雅,儘管 – gsp8181

回答

0

首先,您不應該使用PUT進行部分更新。 PUT是目標資源的完全替代品。所以,爲了做你想做的事,無論是PATCH還是POST。由於您需要在同一操作中更新和創建新的東西,請使用POST。 POST是用於任何未通過HTTP協議進行標準化的操作的方法,因此只要它被正確記錄,您就可以使用它進行任何操作。

而設計REST API

我真的很想知道那個動詞應該設計一個REST API時,應避免將想法來自時,應避免動詞。這是沒有意義的,因爲URI的內部語義在REST中是不相關的。 URI是一個原子標識符,文本對人類的意義對於應用程序來說絕對是無關緊要的。

沒有錯與做:

POST myapi/approval_step/2/approve 

什麼是錯的是這樣的:

POST myapi/approve 

{"approval_step": 2} 

我覺得有人讀的地方,這是錯誤的,由於某種原因,得出結論認爲,這是因爲URI中有一個動詞,並不是因爲資源是由有效負載而不是URI來標識的。

在情況不清楚,更糟糕的例子是做這樣的事情:

POST myapi 

{"method": "approve" 
"args": {"approval_step": 2}} 

這顯然是RPC,沒有休息,與API的所有交互經過一個端點,與有效載荷識別您想要做的一切。這是你應該避免在REST中,而不是「URI中的動詞是錯誤的」廢話。

+0

嘿@Pedro Werneck,我認爲人們習慣於看到這樣的指南:http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful- API。可能來自動詞的想法是代碼味道。 –

+0

是的,我知道那個指南,但我真的是指那個無稽之談的第一個開始。 –

2

當你想符合REST的原則時,並不是在URL中禁止使用動詞。使用它們只是一種難聞的氣味,可能意味着有人試圖重寫協議語義。

例如,

GET /myapi/createApproval 

是可怕的,錯誤的,因爲動詞重寫HTTP動詞GET的意義和誤用它來實現資源的狀態轉換,使通話不安全。

HTTP是網絡的底層協議,並且符合它的語義會在設計API時需要預見的結果。這與方法的冪等性和安全性有關。遵循這些規則可以確保您的API在可擴展性,緩存能力,與代理的一致性等方面很有用。

在我看來,只要您不違反由您的底層協議定義的規則。有人可能會認爲帶動詞的URL是一個有意義的資源標識符。 approve不太直觀認爲的比approval

資源你可以用

PUT myapi/approval_step/2/approval 

去紀念一個步驟的審批和

DELETE myapi/approval_step/2/approval 

將其刪除。

但是,請注意,如果您希望實際開發人員閱讀某些文檔並將其寫入客戶端,則URL的格式似乎相關。就RESTful而言,這是一個比任何動詞都更爲棘手的問題。

在真正的RESTful體系結構中,人們永遠不需要閱讀或理解URL,因爲應用程序客戶端本身可以基於服務返回的超媒體獲取鏈接。這需要使用明確定義的格式,但這不是一件容易的事情。許多據稱是RESTful的API甚至不會去關注HATEOS。

欲瞭解更多信息,請參閱Roy Fielding的博客文章,REST APIs must be hypertext-driven

HATEOAS,它的優點和缺點,以及超媒體驅動的API的設計,資源狀態和應用程序狀態的概念深入描述由Leonard Richardson,Mike Amundsen和Sam Ruby提供的RESTful Web APIs。我的觀點非常好。不僅要學習如何做REST,還要意識到如果你真的想要或需要這樣做。