REST API 是整合多個應用程序的強大工具。雖然 REST API 非常有用，但創建和部署它們到生產環境中是一個非常復雜且耗時的過程。如果您正在構建自己的 REST API，您應該熟悉一些命名 REST API 端點的行業最佳實踐。對于許多開發人員來說，使用開發平臺是一種很好的入門方式。它簡化了開發流程并確保您能夠立即開始。
以下是我們建議的 REST API 端點遵循的命名約定：
REST API 端點是 Web 服務中通信的基石，充當交互點，其中配置了特定的 URL 以接收 Web 請求。它們允許不同的軟件應用程序通過定義它們可以使用的方法和數據格式來相互通信。每個端點都是一個特定的 URL，API 可以在其中訪問所需的資源（例如服務器數據），并使用標準 HTTP 方法（包括 GET、POST、PUT 和 DELETE）執行操作。適當地命名這些端點對于可讀性、可維護性和易于集成至關重要，從而確保無縫的用戶體驗。
當有一條清晰、完善的路徑可供遵循時，瀏覽 API 的數字迷宮就會變得容易得多。這是在命名 REST API 端點時采用最佳實踐的本質。REST（即表述性狀態轉移）提供了一組架構約束，可增強 Web 服務的性能、可擴展性和可修改性。命名約定是這些約束的一個組成部分，它提供了一種系統的方式來構建 API 端點，使其可預測且易于理解。雖然這看起來像是一個小細節，但我們命名端點的方式會對用戶體驗、可維護性和 API 的整體成功產生深遠影響。
所有 REST API 都有一個可以訪問的 URL，例如?https://api.example.com?。此 URL 的子目錄表示不同的 API 資源，可以使用統一資源標識符 (URI) 訪問。對于開發人員來說，這是一種確保名稱有意義且任何人都能理解的簡單方法。例如，URI??https://api.example.com/?users?將返回包含特定服務的用戶的列表。Web API 使人們更容易了解正在使用哪些 Web 服務。
一般來說，URI 應該用名詞來命名，以指定資源的內容，而不是為正在執行的功能添加動詞。例如，您應該使用 https://api.example.com/users ，而不是 https://api.example.com/ getUsers。這是因為 CRUD（創建、讀取、更新、刪除）功能應該已經在 HTTP 請求中指定（例如 HTTP GET https://api.example.com/users）。沒有必要重復這些信息，這使 URI 易于閱讀，同時顯示它是所需的 Get 方法。內容類型標頭是命名 URI 的好方法。在極少數情況下，您可以使用 HTTP 動詞，但最好堅持使用名詞作為其余端點名稱。
使用名詞命名 URI 是 REST API 命名的最佳實踐，但您可能想知道復數名詞還是單數名詞最好。什么時候應該使用單數名詞或復數名詞？一般來說，您應該使用復數名詞來命名 URI。例外情況是當您有一個明顯是單數的概念時，這種情況很少發生。（例如，對于管理用戶，?https://api.example.com/users/?admin??）。?
命名 REST API 端點時，應使用直觀且易于理解的 URI 名稱。考慮一下那些以前從未使用過您的 API 的人檢查 URI 的情況。他們應該能夠輕松猜出使用了哪些單詞以及它們的結構。您絕對應該避免使用縮寫和速記（例如 https://api.example.com/users/123/fn 而不是 https://api.example.com/users/123/first-name）。在某些情況下，某個事物的接受或流行術語就是縮寫，這意味著您可以使用它。（例如 https://api.example.com/users/ids 而不是 https://api.example.com/users/identification-numbers）。記住要保持足夠簡單，以便任何不熟悉您的 API 的人都可以輕松猜出 URI。如果每個人都使用相同的方法來命名他們的 REST API 端點，那么使用起來就會更容易。
您正在命名資源，該資源可能是單例或集合。最終用戶一看到名稱，就會知道它到底是什么。例如，您可以使用“customer”或“users”作為資源名稱。還需要定義子集合。最終看起來像“/users/client-id/accounts/account-id”。如您所見，它清楚地顯示了 URI 的層次結構，即使有人不熟悉您的 API，也可以跟蹤資源。
REST API 通常采用層次結構。例如，https://api.example.com/users/123/first-name 將檢索 ID 號為 123 的用戶的名字。應使用正斜杠（“/”）字符來導航此層次結構并指示您所在的位置。在 URI 中從左到右移動時，它會從一般移動到具體。
雖然正斜杠適合表示 API 的層次結構，但它們在 URL 的末尾并不是必需的。添加這個多余的斜杠會增加復雜性，而不會增加清晰度。例如，您應該使用 https://api.example.com/users，而不是 https://api.example.com/users/。
當 REST API 端點包含多個單詞（例如 https://api.example.com/users/123/first-name）時，應使用連字符分隔單詞。這是使 URI 更易于閱讀的好方法，也是每個人都能理解的通用方法。
人們普遍認為，連字符比下劃線（例如 first_name）或駝峰式大小寫（例如 firstName）更清晰、更方便用戶使用，后者由于使用大寫字母而不被推薦（見下文）。連字符易于輸入，并且所有開發人員都在同一頁面上，它可以簡化 URI 以確保每個人都可以訪問。
盡可能在 API URL 中使用小寫字母。這主要是因為?URI 標準的 RFC 3986 規范指出 URI 區分大小寫（URL 的方案和主機組件除外）。URI 的小寫字母被廣泛使用，也有助于避免因大小寫不一致而引起的混淆。如果您添加大寫字母，您應該意識到這會引起混淆，并且通常會導致用戶錯誤。
特殊字符不僅沒有必要，而且可能會讓熟悉 API 設計和命名的用戶感到困惑。它們并非人人都能輕松使用，而且技術上也很復雜。由于 URL 只能使用 ASCII 字符集發送和接收，因此所有 API URL 都應僅包含 ASCII 字符。
此外，請盡量避免使用“不安全”的 ASCII 字符，這些字符通常 經過編碼 以防止混淆和安全問題（例如，空格字符為“%20”）。URL 的“不安全”ASCII 字符包括空格字符（“ “”）以及括號（“[]”）、尖括號（“<>”）、大括號（“{}”）和豎線（“|”）。盡可能保持名稱簡單，這樣就不會出現任何問題。在大多數情況下，這些與 HTTP 方法相同。
雖然 API 調用的結果可能是特定的文件類型，但文件擴展名（例如 .HTML）在 URI 中被視為不必要的，因為它們會增加長度和復雜性。例如，您應該使用 https://api.example.com/users 而不是 https://api.example.com/users.xml。事實上，如果您稍后更改結果的文件類型，使用文件擴展名可能會給最終用戶帶來問題。例如，您不需要使用 node.js 或類似文件。它可以簡化。
URI 中的文件擴展名通常會造成混淆，如果不知道 URI，也會使直觀理解 URI 變得更加困難。文件擴展名不需要包含在內，還有其他方法可以指示文件類型。這些不應包含在 REST API 設計和名稱中。
如果您想要指定結果的文件類型，則可以使用 Content-Type 實體標頭 。這可以讓用戶知道原始資源使用了哪種媒體類型。這并非總是必要的，但如果您希望保留原始文件類型的記錄，則可以使用此方法。
選擇一種命名 API 端點的系統并堅持使用。您應該記錄您的方法，以便與您一起工作的每個人都知道命名協議。當您的名稱一致時，這可以確保整個系統統一。使用 API 的每個人都會發現使用它們很容易。如果他們不確定特定的 URI，他們可以根據命名協議假設它是什么。
保留所有記錄。雖然有一些普遍理解的指導方針，但您可能希望將流程正式化。當新人加入您的團隊時，他們可以快速訪問 URI 命名協議并遵循這些協議以確保一致性。
REST API 的清晰度和成功在很大程度上取決于您如何命名端點。雖然有一些推薦的做法可供遵循，但了解和避免常見的命名錯誤也同樣重要。以下是一些常見的錯誤做法。
REST API 端點應明確標識特定資源。如果您的端點名稱含糊不清或不具描述性，則可能會讓開發人員和用戶感到困惑。堅持使用簡單、直觀的名稱，清晰地反映相關資源。避免使用可能不是所有用戶都熟悉的神秘縮寫、首字母縮略詞或行業術語。
根據RFC 3986的規定，URI 區分大小寫。API URL 中混合使用大小寫字母可能會導致誤解和潛在錯誤。始終在端點名稱中使用小寫字母，以保證一致性并避免潛在問題。
REST 架構的基石是使用 HTTP 方法（動詞）來操作資源（名詞）。因此，在端點名稱中加入動詞是一種不好的做法，因為 HTTP 請求方法應該已經指定了執行的功能。在端點名稱中包含動詞可能會導致冗余和混亂。
API 版本控制對于在 API 不斷發展時保持向后兼容性至關重要。如果未在端點中包含版本控制，則可能導致對用戶產生重大影響的更改。務必在端點中包含版本（例如“v1”），以確保在 API 不斷發展時順利過渡。
為 API 端點建立有效、清晰且一致的命名約定可以大大增強應用程序的可用性、可維護性和可擴展性。讓我們深入探討正確命名 REST API 端點的好處。
命名良好的 API 端點可以立即告訴您從中可以期待什么，從而提高可讀性和理解力。例如，GET請求/users直觀地暗示獲取用戶列表。這種清晰度簡化了新開發人員的學習曲線并增強了團隊之間的協作。
GET
/users
一致的命名約定可讓您的 API 更可預測且更易于使用。開發人員可以預測端點的結構，從而減少錯誤并加快 API 集成速度。
如果出現問題，命名良好的端點可以加快故障排除過程。當端點反映其功能時，更容易找到和糾正問題，從而提高 生產率并減少停機時間。
隨著應用程序的增長，API 端點的數量也會隨之增加。強大的命名約定有助于有效管理這種增長，確保新端點與現有端點順利集成，從而促進可擴展性。
對于 API 的客戶來說，清晰直觀的端點意味著更順暢、更愉快的體驗。使用您的 API 的開發人員會欣賞結構良好、命名合理的端點背后的周到，使他們更有可能繼續使用您的服務。
通過存儲經常訪問的數據，API 將響應更快，并可能減少后端負載，從而帶來更好的用戶體驗。
緩存通過比從數據庫或服務器獲取數據更快的速度檢索數據來提高性能。這種速度對于提供快速響應的應用程序非常重要，因為用戶希望立即進行交互。緩存還可以通過處理來自緩存的重復請求來減少服務器負載，從而減少數據庫查詢和計算。
可擴展性是另一個關鍵優勢。有效的緩存有助于管理高流量，這將確保您的 API 能夠擴展以滿足不斷增長的需求，而不會影響性能。這對于經歷快速增長或突然流量激增的應用程序來說非常重要。
根據不同的需求，可以實現幾種不同的緩存策略：
Cache-Control
Expires
ETag
Last-Modified
由于需要擔心這么多 REST API 端點命名約定，因此構建自己的 REST API 需要花費這么長時間也就不足為奇了。好消息是，這不必如此，這要歸功于DreamFactory 等API 管理平臺。
API 開發聽起來可能很復雜，但有了正確的 API 管理平臺，您甚至不需要知道如何編寫一行代碼。
一致的命名約定可讓您的 API 可預測、更易于理解和使用。開發人員可以預測端點的結構，從而減少錯誤并提高集成過程的效率。它還可以增強代碼的可讀性和可維護性。
在 REST 中，我們將數據概念化為資源。使用名詞來命名端點符合這一概念，因為它可以清楚地表明端點所公開的資源。另一方面，動詞更適合定義操作，在 RESTful 設計中，這些操作由 HTTP 方法（如 GET、POST、PUT 和 DELETE）表示。
使用復數名詞是 REST API 設計中的常見慣例。它有助于確保一致性，并更好地反映端點返回多個資源的可能性。例如，/userscould 表示一個或多個用戶，而/usermight 則暗示它僅表示單個用戶。
/user
HTTP 方法表示對資源的操作。最常見的是 GET（檢索）、POST（創建）、PUT（更新）和 DELETE（刪除）。通過使用這些方法，我們可以簡化端點名稱，使其僅關注資源。
深度嵌套的端點可能變得復雜且難以管理，從而導致潛在的混亂和錯誤。通常建議將嵌套限制為一個級別，即 ，/users/123/posts而不是像 這樣的更深的嵌套/users/123/posts/456/comments。
/users/123/posts
/users/123/posts/456/comments
命名良好的端點可以更輕松地找到并糾正問題。如果端點的名稱反映了其功能，開發人員可以更快地識別問題，從而提高生產力并減少停機時間。
隨著應用程序的增長和 API 端點數量的增加，強大的命名約定有助于有效管理這種增長。一致且清晰的端點名稱可確保新端點與現有端點順利集成，從而促進可擴展性。
原文鏈接：REST API 接口命名的最佳實踐
<ol id="19emn"></ol>