API 設計的最佳實踐
優(yōu)秀的API設計話題，在很多團隊涌現(xiàn)，這些團隊正在努力完善他們的API策略。
在之前發(fā)布的博客上，我簡要的討論了API設計的重要性。一個設計良好的API應該包含那些好處：你的API應該能提高開發(fā)者經驗、方便的快捷文檔和高可用性。
但優(yōu)秀的API設計究竟應該怎么做?在這個博客中，我將詳細的介紹一些RESTful API的***設計。
一個設計良好的API的特點
一般來說，一個有效的API設計遇有以下特點：
- 易于閱讀和使用。一個設計良好的API應該很容易被使用，其資源和相關操作能夠快速的被使用它的開發(fā)人員記憶。
- 難以誤用。設計良好的API實現(xiàn)和集成將是個簡單的過程，寫出錯誤代碼將變得不太可能。沒有嚴格按照API開發(fā)指南的終端用戶將會得到詳實的信息反饋。
- 完整又簡潔. ***，一個完整的API應該具有成熟的應用防止你的數據被泄露。API完整性會隨著時間的推移而改變，大多數的API設計人員和開發(fā)人員都應在現(xiàn)有基礎上逐步構建新的API。這是每一個使用API的工程師或公司都必須堅持的理念。
為說明下面列出的概念， 我會以一個照片分享的應用程序舉例。 該應用程序允許用戶上傳照片， 以拍攝地點和心情標簽描述照片特征。
集合，資源及其網址
了解資源和集合
資源是REST概念的基礎。 一條資源是一個重要對象，它本身可以被引用。 一條資源含有數據，與其他資源的關系，以及操作方法，以允許訪問和處理相關信息。
一組資源被稱為一個集合。 集合和資源的內容取決于你的組織和消費者的需求。 例如，如果你認為，市場獲得了你的產品用戶群的基本信息會受益， 那么，你就可以將此作為集合或資源。
統(tǒng)一資源定位器(URL)確定了資源的在線位置。 URL指向你API資源存在的位置。 基URL是這個位置的一致部分。
在照片分享應用一例中， 我們可以公開用戶數據，只要用戶通過集合和資源使用該應用程序， 經由適當的URL訪問。
- /users：用戶的集合。
- /users/username1：一個特定用戶的信息資源。
名詞化的URL更好
URL應該是整潔、優(yōu)雅和簡單的，這樣開發(fā)人員更易在他們的web程序中使用你的產品。 很長且難以理解的URL不僅看起來很糟糕，而且在記錄時容易出現(xiàn)錯誤。所以使用名詞應該是很好的。
沒有規(guī)定讓資源名詞使用單數或復數，但是在如果是集合的話使用復數無疑很好的。 具有相似的資源和集合分別保持它們的一致性是較好的做法。
保持這些名詞的自解釋性，有助于開發(fā)人員了解從URL描述的資源, 這最終會使他們使用你的API。
回到照片分享應用程序，它擁有返回集合的公共API /users 、/photos。注意到它們都是復數名詞了嗎? 它們也是自描述的，我們可以推斷出 /users 和/photos分別是獲取產品注冊的用戶信息和分享的照片。
用HTTP方法來描述資源的功能
所有資源都有一組方法，可以對它們進行操作由該接口暴露的數據。
REStful APIs包含主要的HTTP方法，其良好的定義和獨立的功能能夠應對所有資源。這里是RESTful API里常用HTTP方法列表，這些方法定義CRUD如何操作資源和集合。
(如果你想了解PUT和PATCH的不同，可以到StackOverflow上看看這個)
雖然在URL中使用動詞也不錯，但是GET, PUT, POST, DELETE操作已經用于描述了資源的操作，因此在URL中使用動詞代替名詞會顯得比較混亂。
在照片分享app中，/users 和/photos 是一個端點，API的終端消費者可以更直觀的使用RESTful CRUD 進行上述的操作。
響應
提供反饋,以幫助開發(fā)人員成功
在他們使用你的產品時向開發(fā)人員提供良好的反饋，對于提升使用率和用戶維持率是很好的。每一個客戶端的請求和服務端的響應都可以看做是一個消息，在理想化的RESTful 生態(tài)系統(tǒng)中，這些消息必須是自描述的。
良好的反饋對于實現(xiàn)的驗證是積極的，錯誤實現(xiàn)產生的消息可以幫助用戶調試和糾正使用產品的不正確方式。對于API, 錯誤信息是使用API上下文的良好方式之一。
調整你的錯誤與標準HTTP代碼一致。客戶端引發(fā)的錯誤應該使用400類型錯誤，如果是服務端的錯誤應該使用500類型來響應。 一個對資源操作成功后應該返回一個200類型的響應。
有很多的響應代碼。想了解更多, 看看這個REST API教程.
一般來說，使用你的API時有三種可能就結果：
客戶端應用程序的行為是錯誤的(客戶端錯誤–4xx響應代碼)
API行為錯誤 (服務器錯誤- 5 xx響應代碼)
客戶端和API工作正常 (成功– 2xx響應代碼)
成功解決客戶使用你的API時遇到的問題將大大改善開發(fā)人員使用體驗和防止濫用API。 詳細描述這些錯誤，同時保持簡明和整潔。在錯誤消息中提供足夠的信息有助于用戶解決它們的問題，如果你覺得需要更加詳細的信息，***另寫文檔并在此處提供鏈接。
GET 響應例子
一個良好設計的API應該有響應示例，以明白是否成功調用了一個URL。響應示例應該簡單、簡潔和易于理解的。 一個好的經驗法則是：幫助開發(fā)人員在5秒內理解一個成功的響應。回到我們的照片分享應用，我們定義了 /users 和 /photos URL。 /users 應該易數組的形式提供所有注冊的用戶，并且包含用戶名稱和加入日期屬性。
你可以在Swagger(OpenAPI)中使用 API設計工具來定義你的API，詳述如下：
- responses:
- 200:
- description: Successfully returned information about users
- schema:
- type: array
- items:
- type: object
- properties:
- username:
- type: "string"
- example: "kesh92"
- created_time:
- type: "dateTime"
- example: "2010-01-12T05:23:19+0000"
注意數據類型和實例的每個響應項注釋，最終用戶期望的是一個成功的GET調用。成功響應后最終用戶將接收的JSON看起來如下：
- {
- “data”:[
- {
- “Username”:“example_user1”,
- “created_time":“2013-12-23T05:51:14+0000 ”
- },
- {
- “username”:“example_user2”,
- “created_time":“2015-3-19T17:51:15+0000 ”
- }
- ….
- ]
- }
如果用戶調用了這個方法，就應該獲得包含上述數據和一個說明正確調用了的200響應狀態(tài)碼。 同樣的,，一個不正確的調用應該產生適當的400 或500 響應狀態(tài)碼和其它相關信息，以幫助用戶更好地操作。
請求
優(yōu)雅的處理復雜性
你試圖開放的數據包含大量的有利于用戶的屬性，這些屬性描述的基本資源和隔離特定信息，可以通過適當的方法來操作。
一個API應該努力提供完整的信息、數據和資源來幫助開發(fā)者以無縫的方式與之整合。
然而， 完整意味著對你的API考慮通用使用情況。可能會有許多這樣的關系和屬性,單獨為他們定義資源不是好的做法。
資源暴露的數據量也應考慮。如果你暴露得太多，這會對服務器產生消極的影響，特別是對于負載和性能。
上述情況和關系是在設計的API時需要重點考慮的因素，可以使用適當的參數來處理。你可以掃描查詢參數中l(wèi)imit參數來限制響應數據量，或者讓客戶端使用路徑參數來隔離數據。
以我們的照片分享應用作為示例。
它可以用于開發(fā)者獲取在特定位置和特定主題標簽中共享的所有照片的信息。 您可能還想要通過將每個 API 調用的結果數限制為 10，以減輕服務器負載。 如果最終用戶想要找到波士頓的所有照片，并使用 winter 標簽，則請求將是：
- GET /photos?location=boston&hashtag=winter&limit=10
注意現(xiàn)在的復雜性如何被簡化為一個與查詢參數的簡單關聯(lián)。如果您想根據客戶的請求提供特定用戶的信息，則調用：
- GET /users/kesh92
這里的 kesh92 是一個指定的用戶名，它會返回該用戶的地點和加入日期。
這只是朝著API完備性進行參數設計的幾種方式，可以幫助用戶更直觀的使用你的API。
***， 有疑問時，暫時離開它。如果你重新思考了某個資源或集合的功能，應該把它放入下一個迭代中。開發(fā)和維護API是一個持續(xù)的過程，等待正確的用戶反饋可以構建一個健壯的API，以幫助用戶以創(chuàng)造性的方式集成和開發(fā)應用程序。
API設計入門
沒有一個API設計方法能夠一勞永逸解決所有組織的問題。上述的建議僅僅是參考意見和建議，能否采用取決于你的用戶情況和需求。
一個API設計至關重要的主要原因是你的API能幫助到終端用戶，他們的需求就是貫穿你整個API設計的指明燈。
