如何爲單個資源建模RESTful API？

我正在尋找在現有項目之上公開一些域RESTful API。我需要建模的一個實體具有單個文檔：設置。設置是使用應用程序創建的，並且是單例文檔。我想通過設計良好的基於資源的RESTful API公開它。對於許多項目資源如何爲單個資源建模RESTful API？

通常建模的API時，它是這樣的：

GET /employees/ <-- returns [] of 1-* items 
GET /employees/{id}/ <-- returns 1 item 
POST /employees/ <-- creates an item 
PUT /employees/{id}/ <-- updates all fields on specific item 
PATCH /employees/{id}/ <-- updates a subset of fields specified on an item 
DELETE /employees/{id}/ <-- deletes a specific item

選項1：

GET /settings/ <-- returns [] of 1-* items 
[{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" }] 

GET /settings/{id}/ <-- returns 1 item 
{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" } 

PUT /settings/{id}/ 
PATCH /settings/{id}/

：如果我以同樣的方式，則下列API構建模型設置

這對我來說有一些細微差別：

我們返回時，只有1個項目可以和是永遠存在的數組。設置是應用程序創建的單例。
我們需要知道的ID，以請求只返回1項
我們需要一個單獨的ID只是把或修補它

選項2：然後我的頭腦繼續在這個方向：

GET /settings/ <-- returns 1 item 
{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" } 

PUT /settings/ 
PATCH /settings/

該設計消除了以下帶來的細微差別，並且不需要ID爲PUT或PATCH。這對我來說是最一致的，因爲所有請求都具有相同的形狀。

OPTION 3：另一種選擇是將ID添加回PUT和PATCH要求其進行更新，但隨後一個API的用戶必須執行一個GET只是爲了獲得一個單身的ID：

GET /settings/ <-- returns 1 item 
{ "id": "06e24c15-f7e6-418e-9077-7e86d14981e3", "property": "value" } 

PUT /settings/{id}/ 
PATCH /settings/{id}/

這似乎不一致，因爲GET 1與UPDATE 1請求的形狀不同。它也不要求消費者執行GET來找到單身人士的標識符。

有沒有一種首選的方法來建模？
有沒有人有任何關於爲單身人士資源建模RESTful API的參考資料？我目前傾向於選項2，但我想知道是否有我可以研究的良好資源或標準。
是否有迫切的理由要求API消費者爲某個資源的id創建一個GET，然後在更新請求中使用它（也許出於安全原因等）？

來源

2017-03-07 gtaborga

就我所知，選項2是完全RESTful的。

RESTful API背後的核心思想是你操縱「資源」。單詞「資源」是故意模糊不清，這樣它可以指任何重要的是要在specfic應用程序，從而使API如何內容時將忽略什麼內容將要訪問的訪問只專注於。

如果您的資源是單身人士，將ID值賦予它是沒有意義的。ID非常有用，並且通常用於RESTful API，但它們是而不是是使RESTful API成爲API核心的一部分，正如您已經注意到的那樣，實際上會使訪問單例資源變得更加繁瑣。

因此，你應該廢除ID和既有

GET /settings/

和

GET /settings/{id}

總是返回設置單獨的對象。（通過ID訪問不是必需的，但爲了防止有人試用它，這很好）。另外，一定要記錄您的API端點，因此消費者不要指望一個數組:)

回覆：你的問題，

我相信選擇2將是這個造型的首選方式，我相信要求你的消費者爲id做一個GET實際上會有些反模式。

來源

2017-03-07 23:04:37

Resource的ID是Url本身，不一定是Guid或UUID。 Url應該唯一ID entify Resource，在你的情況下，Settings實體。但是，爲了問題的REST，您必須指向你的索引地址此資源（即/路徑）用適當的rel屬性，因此客戶端將不硬編碼地址，比如這個：

GET/
{ .... 
"links": [ 
     { "url" : "/settings", "rel" : "settings" } 
], ... 
}

除了Url不包含Guid，Uuid或任何其他數值之外，沒有任何細節可用於訪問單一資源。

來源

2017-03-07 23:31:20

我認爲這裏的困惑是因爲單詞設置是複數，但資源是單身。

爲什麼不將資源重命名爲/configuration並使用選項2？

這可能不會讓您的API的消費者感到意外。

來源

2017-03-08 01:50:55 MvdD

你可能會推翻它。 HTTP或REST中沒有單例的概念。

GET /settings/非常好。

順便說一句，我們很難將此與DDD聯繫起來 - 至少在您沒有提供更多關於設置在您的域中意味着什麼的上下文時不會。

也可能是因爲您在嘗試在不合適的情況下在設置上添加「帶ID的實體」方法。並非系統中的所有對象都是實體。

來源

2017-03-08 14:25:45 guillaume31

如何爲單個資源建模RESTful API？

回答

相關問題