對於試圖完善其 api 策略的團隊來說，良好的 api 設計是乙個經常出現的話題。
那麼好的api設計到底是什麼？這篇文章將詳細介紹一些設計 restful api 的最佳實踐。
| 精心設計的 api 的特徵
一般來說，乙個有效的 api 設計將具有以下特點：
*** 難以濫用。**實現和整合具有良好設計的 api 是乙個直截了當的過程，出現**編寫不正確的可能性會更小。它具有資訊性反饋，並且不會強迫 api 的終端使用者遵守嚴格的規範。
*** 完整而簡潔。**最後，完整的 api 能讓開發人員針對公開的資料製作成熟的應用程式。大多數 api 設計人員和開發人員會在現有 api 的基礎上逐步構建，使應用程式的完整性隨時間推移而提高。這是每個擁有 api 的工程師或公司在努力實現的目標。
接下來的部分會以**共享應用程式為例，說明一些概念。該應用程式允許使用者上傳**，用這些**的拍攝地點和描述與之相關的情緒的主題標籤來表述。
| 集合、資源及其 url
了解資源和集合
資源是 rest 概念的基礎，它是乙個非常重要的物件，可以被自身引用。資源具有資料、與其他資源的關係以及對其進行操作以允許訪問和操作相關資訊的方法。
一組資源稱為乙個集合。集合和資源的內容取決於組織機構和使用者的要求。例如，如果某組織認為自身某產品使用者群的基本資訊可以為組織帶來利益，就可以嘗試將其作為集合或資源公開，比如像qq在內的各種快捷登入。
在**共享應用程式中，我們可以通過適當的 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
什麼是好的API設計？
摘要 有人言，api設計是程式設計工作中最難的事情。甚至有人認為至少要有10年的工作經驗才能接觸它。不過這裡提出了乙個引人思考的問題 究竟是構建什麼樣的庫需要花費10年的時間去學習？有人言，api設計是程式設計工作中最難的事情。甚至有人認為至少要有10年的工作經驗才能接觸它。其實通過好的培訓或導師學...
什麼是好的API設計？
什麼是api？我們只要是在進行程式設計我們就需要不停的設計api。api簡單來講可以是乙個呼叫的函式，乙個介面。抽象來說，介面是乙個內聚系統暴漏給外部的一切資訊，包含但不限於 api就像乙個人一樣，我們和乙個api打交道的時候需要了解這個人的特性偏好等，有的人很好相處，而有的人讓人很頭疼，尤其是你不...
好的API設計
1 keynote.pdf 2 api design.pdf 最近在重構公司的乙個互動中介軟體，在重新設計api及總體架構的時候思考了許多，不禁萌發了乙個疑問，什麼樣的api才算是乙個設計良好的api呢？參考了許多的資料，做一下總結。主要來自這個keynote 我們只要是在進行程式設計我們就需要不停...