在Fielding的論文中 ，資源被描述為：

“可以命名的任何信息”……“文檔或圖像，臨時服務（例如，“洛杉磯今天的天氣”），其他資源的集合，非虛擬對象（例如，人） 等等。 換句話說，任何可能成為作者超文本 引用 目標的概念都 必須符合資源的定義。 資源是 到一組實體 的概念性映射 ，而不是在任何特定 時間 點對應于該映射的實體 。”

定義資源既是科學也是藝術 。 它需要領域知識和API體系結構技能。 下面詳細介紹的以下幾點用作清單，可以幫助您確定資源。

資源必須包含業務說明

• 商業描述應為簡單散文中的3-4個句子，以說明資源是什么。
• 對您的系統有一定了解的開發人員應該能夠理解該描述
• 資源的任何警告均應明確

資源應單獨使用

這類似于定義微服務邊界的準則，在這種情況下，應將微服務視為自身有用。 同樣，資源應單獨使用。

例如，代替：

/street-address/{id} RESPONSE { "street1" : "String" , "street2" : "String" }

和

/address-extra/{id} RESPONSE { "city" : "String" , "country" : "String" }

它應該是：

/address/{id} RESPONSE { "street1" : "String" , "street2" : "String" , "city" : "String" , "country" : "String" }

如果資源本身沒有用，并且總是需要后續請求，則意味著代碼將不可避免地變得更加復雜，并且第二個請求將對性能造成影響

使用適當的名詞

最好使用簡單名詞而不是復合名詞。 例如，
地址優于AddressInfo或AddressDetail 。 這是一條一般規則，總會有例外 。

如果使用多個資源表示同一數據的不同視圖，例如： Address和AddressDetail ，則使用簡單名詞，例如
地址第一。 然后，如果第二種表示形式更詳細地使用
ResourceNameDetail，或者如果不夠詳細，請使用ResourceNameSummary 。 例如，假設需要引入一個地址類型資源：

地址首先介紹

如果需要更詳細的地址后續視圖，則新資源應稱為AddressDetail

如果需要的后繼地址視圖不太詳細，則新資源應稱為AddressSummary

如果僅在READ中使用它，它是否需要成為資源？

如果僅在讀取請求中使用過資源，而從未在寫入 （ 創建，部分更新，完全更新，刪除等 ）請求中使用過資源，則是否需要將其定義為具有自己的URI的資源是可疑的。 可以將其添加到父負載中，如果擔心負載會變得太復雜，則父可以僅提供一個稀疏查詢-客戶端可以根據API請求確定要返回的內容。

資源應符合統一接口

統一的接口是良好API設計的重要組成部分。 如果創建，讀取，更新，刪除等操作以一致的方式進行，則意味著代碼更加一致，可重用且更易于維護。

這表示：

GET /addresses/{id}

和

GET /addresses

必須返回相同的地址數據結構來表示一個地址。

GET /addresses/{id} RESPONSE { "id" : "546" , "street1" : "String" , "street2" : "String" , "city" : "String" , "country" : "String" }

和

GET /addresses RESPONSE { "elements" : [ { "id" : "546" , "street1" : "String" , "street2" : "String" , "city" : "String" , "country" : "String" }, ... ] }

同樣，對于寫入有效負載，數據結構應該相同。 因此，更改street1的部分更新將是：

POST /addresses/{id}/edit REQUEST { "street1" : "Walkview" } RESPONSE { "id" : "546" , "street1" : "Walkview" , "street2" : "Meadowbrook" , "city" : "Dublin" , "country" : "Ireland" }

而不是像

POST /addresses/{id} REQUEST { "newStreet1Value" : "Walkview" }

從資源的角度來看，數據結構必須一致。 不同的數據結構意味著不同的資源，應使用不同的名稱命名并具有自己的路徑。

不要暴露一切

如果您的數據庫模型非常復雜，則不需要在API級別公開所有屬性。 有些字段只能保留用于后臺處理，而不能顯示在UI上。 此類屬性永遠不應包含在JSON API中。

在將屬性添加到JSON資源時，請考慮：

• API中應僅公開您確定客戶端感興趣的字段
• 如果不確定，請忽略該屬性。 稍后添加屬性，然后刪除已經公開的屬性的風險要低得多。

API模型不應盲目地反映數據庫關系模型或OO模型

在數據庫建模方法中，使用規范化數據或折疊繼承層次結構。 在面向對象的設計中，諸如多態，繼承層次結構等技術被用于促進諸如代碼重用之類的事情并減少耦合。

資源建模不必遵循這些技術。 API的使用者不關心數據是全部放在一個表中還是在多個表中進行了規范化。 通常，API以易于使用的格式返回數據，并且在客戶端變得有用之前不需要客戶端進行太多其他映射。

使用分層數據避免重復

與諸如CSV之類的平面格式相比，分層數據的優點之一是它提供了一種避免重復的機制。 例如，考慮一個數據結構，其中包含人員列表以及他們所在的團隊。在CSV中，這是：

team, firstname, lastname Liverpool, Mo, Salah Liverpool, Andy, Roberston

在JSON中，可能是：

{ "team" : "Liverpool" , "players" : [ { "firstName" : "Mo" , "lastName" : "Salah" }, { "firstName" : "Andy" , "lastName" : "Roberston" }, ... ] }

使用分層數據使上下文清晰

分層數據的另一個優點是它有助于提供上下文。 要了解平面數據結構，您需要了解生成數據結構的查詢是什么，以了解其含義。 例如，考慮一堆包含日期范圍的行。

name, fromDate, toDate, holidays Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false

您可以假設當Tony休假時會有新的一行。 但是如果還有另一列怎么辦

name, fromDate, toDate, holidays, sick, Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true

日期范圍是否對應于假期，疾病或兩者兼而有之？

如果我們能獲得更多數據，也許會更清楚……

name, fromDate, toDate, holidays, sick, Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true Tony, 2018 - 03 - 02 , 2018 - 04 - 01 , false , false

現在看來，日期范圍所對應的是一種病，這只是一個巧合，它排列了一個假期。 但是，當我們獲得更多數據時，此理論將失敗：

name, fromDate, toDate, holidays, sick, Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true Tony, 2018 - 03 - 02 , 2018 - 04 - 01 , false , false Tony, 2018 - 04 - 02 , 2018 - 05 - 01 , true , false

平面數據結構的問題在于，只能使數據自我描述。 如果沒有任何信息，它將變得更加復雜。 例如：

name, fromDate, toDate, holidays, sick, Tony, 2018 - 01 - 01 , 2018 - 02 - 02 , true , false Tony, 2018 - 02 - 03 , 2018 - 03 - 01 , false , true Tony, 2018 - 03 - 02 , 2018 - 04 - 01 , false , false Tony, 2018 - 04 - 02 , 2018 - 05 - 01 , true , false Tony, 2018 - 05 - 02 , 2018 - 06 - 01 , null , false Tony, 2018 - 06 - 02 , 2018 - 07 - 01 , null , false Tony, 2018 - 07 - 02 , 2018 - 07 - 08 , true , false Tony, 2018 - 07 - 08 , 2018 - 07 - 09 , true , null

不可避免的是，處理該數據將是錯誤的。 我們可以用以下分層格式表示相同的數據：

{ "name" : "tony" , "holidays" : [ { "fromDate" : "fromDate" "2018-01-01" , "toDate" : "2018-02-02" }, { "fromDate" : "fromDate" "2018-04-02" , "toDate" : "2018-05-01" }, { "fromDate" : "2018-07-02" , "toDate" : "2018-07-09" } ], "sick" : [ { "fromDate" : "2018-02-03" , "toDate" : "2018-03-01" } ] }

現在，數據更加自我描述。 很清楚，日期范圍是假期還是病假。

資源關系

資源本身只能描述自己。 資源模型描述資源之間的關系。 這將表明：

• 資源之間的依賴關系。 存在特定資源需要哪些資源，或者當特定資源發生更改時會影響哪些資源：更新或刪除。
• 數據導航–在大域模型中，如果向模型的使用者提供導航和方向感，則更容易理解和遵循。 尤其是何時進行導航（資源松散連接）與向下導航（資源牢固連接）可以區分開

資源不僅應該考慮實現HATEOAS的超媒體鏈接； 當資源使用超媒體鏈接描述它們所鏈接的內容時，它是表達資源模型的一種非常強大的機制。 優勢包括：

• 它將大型域模型分成更易于管理的部分。 通常，用戶只對模型的特定部分感興趣。 當“資源”自己描述自己的關系時，這意味著將一個大型的復雜模型分解為易于消化的部分，并且用戶可以更快地獲取所需的信息。
• 資源模型是自我描述的，并與代碼保持同步。 一切都在同一地點。

明確父母與子女的關系

子級自我描述了父級URL層次名稱間距。 父資源具有一種或多種類型的子代，應通過提供指向子代的鏈接來闡明這一點。 例如，如果一個團隊有一個玩家。 團隊有效負載應對此進行明確說明。

REQUEST https: //api.server.com/teams/4676 RESPONSE { "id" : "34533" , ..., "_links" : { "self" : " https://api.server.com/teams/4676 " , "players" : " https://api.server.com/teams/4676/players " } }

明確對等關系

這與上面的類似，只不過它用于存在于不同層次名稱空間中的資源。 因此，例如，假設團隊在部門1中。應該在團隊的部門屬性中包含一個鏈接。

REQUEST https: //api.server.com/teams/4676 RESPONSE { "id" : "34533" , "division" : { "name" : "Division 1" , "_links" : { "self" : " https://api.server.com/divisions/1 " } }, ..., "_links" : { "self" : " https://api.server.com/teams/4676 " , "players" : " https://api.server.com/teams/4676/players " } }

明確鏈接到其他表示形式

如果將數據建模為具有多個代表數據不同表示形式的資源，則這些資源還應包括彼此的鏈接。

REQUEST https: //api.server.com/teams/4676 RESPONSE { "id" : "34533" , "division" : { "name" : "Division 1" , "_links" : { "self" : " https://api.server.com/divisions/1 " } }, ..., "_links" : { "self" : " https://api.server.com/teams/4676 " , "players" : " https://api.server.com/teams/4676/players " , "teamDetails" : " https://api.server.com/teamDetails/4676 " } }

翻譯自: https://www.javacodegeeks.com/2019/06/defining-resource.html

總結

以上是生活随笔為你收集整理的定义资源的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。