前言
原文地址：REST Resource Naming Guide
資源的定義：
在 REST 中，主要資料表示為資源；REST 中資訊的關鍵抽象是一種資源； 可以命名的任何資訊都可以是資源：文件或影象，臨時服務（例如“洛杉磯的今天天氣”），其他資源的集合，非虛擬物件（例如人）等等。 換句話說，任何可能是作者超文字引用目標的概念都必須符合資源的定義。 資源是對一組實體的概念對映，而不是與任何特定時間點的對映相對應的實體。
資源可以是單例或集合。
例如，“customers”是一個集合資源，“customer”是一個單例資源（在銀行領域）。 我們可以使用URI“/ customers”來識別“customers”集合資源。 我們可以使用URI“/ customers / {customerId}”識別單個“客戶”資源。
資源也可以包含子集合資源。
例如，可以使用URN“/ customers / {customerId} / accounts”（在銀行業務域中）來識別特定“客戶”的子收集資源“賬戶”。
類似地，子集合資源“帳戶”內的單個資源“帳戶”可以標識如下：“/ customers / {customerId} / accounts / {accountId}”。
REST API使用統一資源識別符號（URI）來定位資源。
REST API設計者應該建立URI，將REST API的資源模型傳達給潛在的客戶端開發人員。 當資源命名良好時，API直觀且易於使用。 如果做得不好，那麼相同的API會感覺難以使用和理解。
統一介面的約束部分通過URI和HTTP動詞的組合來解決，並且根據標準和約定使用它們。
以下是為新API建立資源URI時可以使用的一些提示。
使用名詞表示資源
RESTful URI應該引用作為事物（名詞）的資源而不是引用動作（動詞），因為名詞具有動詞不具有的屬性 - 類似於具有屬性的資源。 資源的一些示例是：
系統的使用者
使用者帳戶
網路裝置等
他們的資源URI可以設計如下：
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/
http://api.example.com/user-management/users/{id}
複製程式碼為了更清楚，讓我們將資源原型劃分為四個類別（文件，集合，儲存和控制器），然後您應始終將資源放入一個原型，然後始終如一地使用它的命名約定。 為了資源的一致性，請抵制去設計資源的誘惑，這些資源將是不止一個原型的混合體。
文件
文件資源是一種類似於物件例項或資料庫記錄的單一概念。 在REST中，您可以將其視為資源集合中的單個資源。 文件的狀態表示通常包括具有值的欄位和指向其他相關資源的連結。
使用“單數”名稱表示文件資源原型：
http://api.example.com/device-management/managed-devices/{device-id}
http://api.example.com/user-management/users/{id}
http://api.example.com/user-management/users/admin
複製程式碼集合
集合資源是伺服器管理的資源目錄。 客戶可以建議將新資源新增到集合中。 但是，要由集合選擇是否建立新資源。 集合資源選擇它想要包含的內容，並決定每個包含的資源的URI。
使用“複數”名稱表示集合資源原型：
http://api.example.com/device-management/managed-devices
http://api.example.com/user-management/users
http://api.example.com/user-management/users/{id}/accounts
複製程式碼儲存
儲存是客戶端管理的資源庫。 儲存資源允許API客戶端放入資源，將其退出，並決定何時刪除它們。 儲存永遠不會生成新的URI。 相反，每個儲存的資源都有一個客戶端在最初放入儲存時選擇的URI。
使用“複數”名稱表示儲存資源原型：
http://api.example.com/cart-management/users/{id}/carts
http://api.example.com/song-management/users/{id}/playlists
複製程式碼控制器
控制器資源模擬程式概念。 控制器資源就像可執行函式，帶有引數和返回值; 輸入和輸出。
使用“動詞”表示控制器原型：
http://api.example.com/cart-management/users/{id}/cart/checkout
http://api.example.com/song-management/users/{id}/playlist/play
複製程式碼保持一致性
使用一致的資源命名約定和URI格式，以最小化和最大可讀性和可維護性。 您可以實現以下設計提示以實現一致性：
使用正斜槓（/）表示層次關係
正斜槓（/）字元用於URI的路徑部分，以指示資源之間的層次關係。 例如：
http://api.example.com/device-management
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices/{id}
http://api.example.com/device-management/managed-devices/{id}/scripts
http://api.example.com/device-management/managed-devices/{id}/scripts/{id}
複製程式碼不要在URI中使用尾部正斜槓（/）
作為URI路徑中的最後一個字元，正斜槓（/）不會新增語義值，並可能導致混淆。 最好完全放棄它們。
http://api.example.com/device-management/managed-devices/
http://api.example.com/device-management/managed-devices /*This is much better version*/
複製程式碼使用連字元（ - ）來提高URI的可讀性
要使您的URI易於掃描和解釋，請使用連字元（ - ）字元來提高長路徑段中名稱的可讀性。
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable
http://api.example.com/inventory-management/managedEntities/{id}/installScriptLocation //Less readable
複製程式碼不要使用下劃線（_）
可以使用下劃線代替連字元作為分隔符 - 但是根據應用程式的字型，下劃線（）字元可能會在某些瀏覽器或螢幕中被部分遮擋或完全隱藏。
**為避免這種混淆，請使用連字元（ - ）而不是下劃線（）。**
http://api.example.com/inventory-management/managed-entities/{id}/install-script-location //More readable
http://api.example.com/inventory_management/managed_entities/{id}/install_script_location //More error prone
複製程式碼在URI中使用小寫字母
方便時，URI路徑中應始終首選小寫字母。
RFC 3986 將URI定義為區分大小寫，但方案和主機元件除外。 例如：
http://api.example.org/my-folder/my-doc //1
HTTP://API.EXAMPLE.ORG/my-folder/my-doc //2
http://api.example.org/My-Folder/my-doc //3
複製程式碼在上面的例子中，1和2是相同的，但3不是。因為它使用大寫字母的My-Folder。
不要使用副檔名
副檔名看起來很糟糕，不會增加任何優勢。 刪除它們也會減少URI的長度。 沒理由保留它們。
除了上述原因，如果您想使用檔案擴充套件突出顯示API的媒體型別，那麼您應該依賴於通過Content-Type標頭傳達的媒體型別來確定如何處理正文的內容。
http://api.example.com/device-management/managed-devices.xml /*Do not use it*/
http://api.example.com/device-management/managed-devices /*This is correct URI*/
複製程式碼切勿在URI中使用CRUD函式名稱
URI不應用於指示執行CRUD功能。 URI應該用於唯一標識資源，而不是對它們的任何操作。 應使用HTTP請求方法來指示執行哪個CRUD功能。
HTTP GET http://api.example.com/device-management/managed-devices //Get all devices
HTTP POST http://api.example.com/device-management/managed-devices //Create new Device
HTTP GET http://api.example.com/device-management/managed-devices/{id} //Get device for given Id
HTTP PUT http://api.example.com/device-management/managed-devices/{id} //Update device for given Id
HTTP DELETE http://api.example.com/device-management/managed-devices/{id} //Delete device for given Id
複製程式碼使用查詢引數過濾URI集合
很多時候，您會遇到需要根據某些特定資源屬性對需要排序，過濾或限制的資源集合的要求。 為此，請不要建立新的API - 而是在資源集合API中啟用排序，過濾和分頁功能，並將輸入引數作為查詢引數傳遞。 例如：
http://api.example.com/device-management/managed-devices
http://api.example.com/device-management/managed-devices?region=USA
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.example.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
複製程式碼