別再設計易碎的WebAPI

寒凝雪發表於2017-08-01
WebAPI

原文作者Mathieu Fenniak在博文中大呼：不要再設計易碎的Web API 了，否則你的合作伙伴或第三方開發者會因此恨你，而離你遠去的。他認為，想設計出相對穩定、牢固的API，關鍵在於以應用目的為中心。文中還分享了設計優秀API需要注意的幾點事項，我們一起來看下：

如果破壞了API，客戶會因此而恨你

很多Web API釋出後，它就像被牢牢刻在石頭上無法做出相容改變，這是個可怕的現象。倘若你破壞了API，你的客戶會因此而恨你，緊接著就是你的老闆。因此，你必須對該API進行更新、維護。

如果API設計的很好，那麼它不會這麼脆弱

減少其脆弱性或增加其韌性是管理API設計的方式之一，其關鍵在於以應用目的為中心做設計。也就是SOA領域，所謂的面向業務（business-orientation）。也許這個概念很難理解，下面的這個示例能很好的說明這一點：

URL之間的區別是什麼呢？

http://api.fbi.gov/wanted?order_by=notoriety,desc&limit=10&page=1&fields=name,aka,known_associates,reward,description,last_seen

這是一份來自美國聯邦調查局的列表。該API包含了許多功能：你可以預定任何領域，按照升序或者降序進行排列；可以指定結果計數 ；可按頁查詢並且還根據指定詳細資訊進行檢索。

對比看下這個URL：

http://api.fbi.gov/wanted/most

兩個URL雖然有著相同的目標，但是執行方式不一樣。第一個是名程式設計師設計的，他能提供任何你想要的功能。設計中沒有描述使用者的意圖，但卻利用請求定義詳細資訊來替代。

第二個URL意圖則非常明顯，顯示聯邦調查局頭號通緝犯名單，模糊的細節，這是根據意圖來進行設計的。

根據”意圖“設計API，減少其脆弱性，有哪些優勢呢？

易使用——沒有複雜的程式、複雜的細節，易於學習；
靈活性——意向驅動API可隨著伺服器端的變化而變化；
一致性——一致性是API設計必備的一大特性；
鬆耦合——這是向後相容性問題。你只需返回一個固定的值，後端相容在意向驅動API中會執行的很好；
可優化——當對資料庫進行更新時，可計算優化而不是在內建的需求上，這比優化每個組合的程式設計要困難得多；
可快取——易快取。程式設計師的設計使得快取困難（正常可查詢引數）和無效（比如限制=5 / 10 / 15快取未被命中）；
易開發—— 由於高複雜性使得開發和測試測試程式設計師的 API變得更加困難和耗時。
高效驗證模型快取 — — 快速檢查 If-None-Match/If-Modified-Since HTTP標頭並作出”304 Not Modified”響應。
但是，我需要一個更加通用的API設計……

為什麼需要通用的API設計？這是因為意向會讓你設計出更好的API。比如，API的靈活性。靈活的API非常有助於於開發使用者介面，允許按欄位排序、可自定義分頁、 排序和篩選或搜尋。

此外，銘記UI意圖，還可以提供一個易於使用、開發、靈活、一致、鬆耦合、可優化、可快取和高效的API的設計決策。

DRY原則（Don’t repeat yourself）

在執行過程中不要使用重複原則，但在API設計中無須擔心重複設計。如果你提供了多個API端點可根據不同意向來檢索相似的物件，從常見的程式碼路徑開始吧。 為使用者提供更多具體的服務，你需要不斷對API進行維護。

這個真的適用於現實的API領域嗎？

這是GitHub提交的一份Status API示例，通過持續整合服務來標記儲存庫版本。

定義特定的功能：指定一個國家修訂的版本庫
GitHub會自動將請求相關聯的，顯示在一起
無HTML 或可自定義的國家 ；API 有極少數量的資料需求。
面向未來： 它以簡約的方式滿足定義的問題。
狀態相關修訂 ；提交新增更多的請求工作。
GitHub 具有靈活性，可以進行更改，而不會破壞相容性：1. 對於API，GitHub暫不支援重寫功能整個請求功能；2.可適用於其他UI領域；3. 如果 GitHub變成MercurialHub、SubversionHub、PerforceHub、 CvsHub、RcsHub，API可同樣被應用。
GitHub靈活顯示提交狀態： 可在移動應用中顯示狀態、本地化的文字易合併。
還有個真實的例子 Twilio’s AvailablePhoneNumbers API，目的是為了搜尋電話號碼分配到您的賬戶中，這個看起來就像典型的API集合，但是細節和意圖關聯並不大。

總結：

綜上所述，不再設計脆弱的Web API，我們得出幾點：1.根據自己的意向設計API；2. 在細節上是模糊的；3.提供多個API以區分使用者意向；4. 通過分享常見的實現方式而不是提供一個通用的服務來減少程式碼重複。

英文出自： Mathieu.Fenniak

本文來自雲棲社群合作伙伴“doNET跨平臺”，瞭解相關資訊可以關注“opendotnet”微信公眾號


相關文章