對于試圖完善其 API 策略的團隊來說，良好的 API 設計是一個經常出現的話題，
API 設計的重要性相信不需要贅述，精心設計的 API 的好處包括：更好開發人員體驗、更快的檔案編制以及更高的 API 使用率，
那么好的API設計到底是什么？這篇文章將詳細介紹一些設計 RESTful API 的最佳實踐，
| 精心設計的 API 的特征
一般來說，一個有效的 API 設計將具有以下特點：
*** 易于閱讀和使用，**一個設計良好的 API 通常都易于使用，并且它的資源和相關操作可以被不斷使用它的開發人員快速記住，
*** 難以濫用，**實作和集成具有良好設計的 API 是一個直截了當的程序，出現代碼撰寫不正確的可能性會更小，它具有資訊性反饋，并且不會強迫 API 的最終使用者遵守嚴格的規范，
*** 完整而簡潔，**最后，完整的 API 能讓開發人員針對公開的資料制作成熟的應用程式，大多數 API 設計人員和開發人員會在現有 API 的基礎上逐步構建，使應用程式的完整性隨時間推移而提高，這是每個擁有 API 的工程師或公司在努力實作的目標，
接下來的部分會以照片共享應用程式為例，說明一些概念，該應用程式允許用戶上傳照片，用這些照片的拍攝地點和描述與之相關的情緒的主題標簽來表述，
| 集合、資源及其 URL
了解資源和集合
資源是 REST 概念的基礎，它是一個非常重要的物件，可以被自身參考，資源具有資料、與其他資源的關系以及對其進行操作以允許訪問和操作相關資訊的方法，
一組資源稱為一個集合，集合和資源的內容取決于組織機構和使用者的要求，例如，如果某組織認為自身某產品用戶群的基本資訊可以為組織帶來利益，就可以嘗試將其作為集合或資源公開，比如像qq在內的各種快捷登錄，
統一資源定位符 (URL) 標識資源的在線位置，此 URL 指向 API 資源所在的位置，base URL 是此位置的一部分，
在照片共享應用程式中，我們可以通過適當的 URL 訪問的集合和資源公開有關使用該應用程式的用戶的資料，
名詞可以更好地描述 URL
base URL 應該整潔、優雅且簡單，以便使用該產品的開發人員可以輕松地在他們的 Web 應用程式中使用它們，一個又長又難讀的基本 URL 不僅不好看，而且在嘗試重新編碼時也容易出錯，以名詞命名 URL 應該始終被作為最優解，
我們在設計時，通常沒有關于保持資源名詞單數或復數的規范，但建議保持集合復數，在所有資源和集合中分別使用相同的復數是一種很好的做法，可以保持描述的一致性，
保持這種命名方式，有助于開發人員理解URL所描述的資源型別，方便他們快速使用這些 API，
說回照片共享應用程式，假設它有一個公共 API，其中包含 /users 和 /photos 作為集合，一目了然，這些都是復數的名詞，由此我們可以推斷出 /users 和 /photos 分別提供有關產品注冊用戶群和共享照片的資訊，
使用 HTTP 方法描述資源功能
所有資源都有一組可以針對它們進行操作的請求方法，用以處理 API 公開的資料，
RESTful API 主要由 HTTP 請求方法組成，這些請求方法對任何資源具有明確定義的獨特操作，以下是常用 HTTP 請求的串列，這些請求定義了 RESTful API 中任何資源或集合的 CRUD 操作，
將動詞排除在 URL 之外是一個好主意，GET、PUT、POST 和 DELETE 操作已用于對 URL 描述的資源進行操作，因此在 URL 中使用動詞而不是名詞會使處理資源變得混亂，
在照片共享應用程式中，以 /users 和 /photos 作為端點，API 的最終使用者可以使用上述 RESTful CRUD 操作輕松直觀地使用它們，
| 回應
提供反饋以幫助開發人員取得成功
在開發人員使用產品時，提供的良好的反饋回應，對提高使用率和留存率大幫助極大，每個客戶端請求和服務器端回應都是一條訊息，在理想的 RESTful 生態系統中，這些訊息必須是自描述的，
好的反饋包括對正確實作的自動驗證，以及對不正確實作的詳細報錯，這可以幫助用戶除錯和糾正他們使用產品的方式，
調整錯誤可以使用標準 HTTP 代碼，對于報錯，客戶端呼叫應該有對應的 400 型別的錯誤代碼與之關聯；如果存在任何服務器端錯誤，則必須將對應的 500 回應與它們相關聯，使用資源的成功請求方法，應回傳 200 型別的回應，
一般而言，使用 API 時會出現三種可能的結果：
*** 客戶端應用程式運行錯誤（客戶端錯誤 – 4xx 回應代碼），**
*** API 行為錯誤（服務器錯誤 – 5xx 回應代碼），**
*** 客戶端和 API 作業（成功 - 2xx 回應代碼），**
當使用者在使用 API 遇到障礙時，引導他們成功完成，這將大大有助于改善開發人員體驗和防止 API 濫用，而很好地描述這些錯誤回應，需要保持簡單和整潔，除了這些，還需要在錯誤代碼中為最終使用者提供足夠的資訊，才能幫助他們開始修改調整，如果覺得簡單描述不夠，那可以再提供指向其他檔案的鏈接，
舉例說明所有的 GET 回應
一個設計良好的 API 應當有對應的例子，對一個URL獲得成功的回應，此示例回應應該簡單、明了且易于理解，一個好的經驗法則是幫助開發人員在五秒內準確了解成功的回應會給他們帶來什么，
回到我們的照片共享應用程式，我們定義了一個 /users 和一個 /photos URL，/users 集合將在陣列中提供所有已注冊應用程式的用戶的用戶名和加入日期，
可以使用像 Eolink 這樣的 API設計開發工具，在 OpenAPI 規范中定義 API，如下所示：
請注意終端用戶可以從成功的 GET 呼叫中獲得的每個回應項中描述的資料型別和示例，終端用戶將接收JSON 格式的成功回應如下所示，
如果終端用戶使用 GET 方法成功呼叫終端點，那么用戶應獲取上述資料以及 200 回應代碼來驗證此為正確用法，同樣，不正確的呼叫，應反饋對應的 400 或 500 回應代碼以及相關資訊，以幫助用戶更好地對集合進行操作，
| 請求
優雅地處理復雜的問題
嘗試公開的資料可以通過許多屬性來展示，這些屬性可能對使用該 API 的最終消費者有益，這些屬性描述了基本資源并隔離了可以使用適當方法操作的特定資訊資產，
API 應盡量保證完整度，并提供所有必需的資訊、資料和資源，以幫助開發人員以無縫方式與它們集成，
但是，完成度意味著要考慮 API 的常見用例，可能有無數的情景關聯和屬性，去定義它們中的每一個資源并不是一個好的做法，
還應考慮資源公開的資料量，如果試圖加載出來很多資料，可能會對服務器產生負面影響，尤其是在負載和性能方面，
上述情況和關系是 API 設計中的重要考慮因素，可以使用適當的引數進行處理，可以掃描屬性并限制查詢引數中“?”后面的回應，或者使用路徑引數隔離客戶端正在使用的資料的特定組件，
讓我們以我們的照片共享應用程式為例，
開發人員可以使用它來獲取有關在特定位置和特定主題標簽共享的所有照片的資訊，我們還希望將每個 API 呼叫的結果數限制為 10，以防止服務器負載，如果最終用戶想要在波士頓找到帶有 #winter 標簽的所有照片，呼叫將是：
請注意，復雜的問題現在已被簡化為與查詢引數的簡單關聯，如果您想根據客戶的請求提供有關特定用戶的資訊，則呼叫將是：
其中 kesh92 是 users 集合中特定用戶的用戶名，將回傳 kesh92 的位置和加入日期，
以上是一些可以設計引數以實作 API，完成并幫助開發人員直觀地使用 API 的一些方法，
最后，如果對特定資源或集合的功能有第二個想法，請將其留待下一次迭代，開發和維護 API 是一個持續的程序，等待合適用戶的反饋有助于構建強大的 API，使用戶能夠以創造性的方式集成和開發應用程式，
圖中所使用的的介面管理工具是eolink，感興趣可以自行使用：www.eolink.com
轉載請註明出處，本文鏈接：https://www.uj5u.com/qita/457547.html
標籤：其他