軟體架構設計：API 設計準則（一）、API 的設計開發與挑戰

前言

最近因緣際會地接下了一門課，這門課是要講授關於 API 開發與設計原則和最佳實踐等相關的內容，雖然我不是第一次接觸這個主題，也曾開發過 2 個 Web API Framework 框架 (以下的 API 均代表 Web API)，只不過，這企業內部 API 開發框架，我們大部分以專案開發的角度來看 API 與 傳統 SPA 前後台網站設計與開發的角度在看每一件事情：像是（分析=>設計=>開發=>測試=>佈署..等）這是大部分開發者熟的純軟體工程，但是切換到 API 的思維會有些不同，這倒也不是說原有的軟體工程不管用，API 依舊是軟體開發出來的，但是整個軟體生態的改變會間接 或者 直接影響軟體服務之間『操作』或『取得』其他服務的方式，尤其在 Cloud 應用與移動裝置的應用會更加的劇烈，一個裝置使用一個公開的第三方服務已經是一個很常見的應用場景（比如：比如物流商與超商之間 API 的對接、線上售票系統與 iBon 之間的對接、或者代收服務等，這些都是 API 跨領域對接最典型的服務），而這邊會談到的是更多直接是以 API 交付出來的雲端服務 Cloud Services、甚至是企業端的平台服務等。

傳統的軟體開發切換到 API 的設計與開發會有那些挑戰？這些我們等一下談。

從軟體工程切換至 API 開發的挑戰

我們常見的軟體工程，不外乎圍繞著專案開發 或 產品開發，這些軟體的終端使用者大都是『人』會會有人機介面，所以不管你是推行 Agile 的軟體開發或是 Kanban 或是 Scrum，我們的最終目標可能都還是完成哪個業務單位『人』想要的『（東西 / 產品）』或者是『市場』（可能）需要的產品。

切換到 APIs 變成 API 與 APIs 協作溝通形成一個最佳的實踐、或 Solutions，你的系統也許是第三方的 API 服務提供者；也許是你也是 GCP/Azure/AWS 等 Cloud 供應商的用戶端，你的軟體系統也是由多個 APIs 所組合而成的 "大系統"，這些 APIs 之間有幾個首要的幾個挑戰要先解決。

(1). 對通訊協定的選擇

也就是像是 HTTP/gRPC/MQTT.. 等等，通訊協定是 APIs 彼此之間溝通的重要的，或是必要的手段，在不同的場景使用適合的通協定是重要的任務，比如 HTTP 比較適合粗粒度的訊息交換，所有通訊協定 HTTP 效率也是最差的，但是 HTTP 最為『開放』與『廣泛』幾乎沒有什麼網路的交換器（Networking/Bridge/Node/Switch..）不支援HTTP，幾乎都支援，但若要有較好的效率可採用 Socket 或像是 MQTT 等，進行比較細粒度更高的資料交換與溝通。

(2). 第二個是與『開發人員之間的溝通』

因為良好的 API 開發流程須具備良好的 Contracts/Docuemnts 與 API Version Control 版控機制，因為對 API 的開發者而言，API 能提供線上即時的 Documents 對開發這而言就是最好的用戶介面，開發者透過文件才有辦法知道一個 API 的操作方式與時機，Docuemnts 還能告訴開發者如何混和不同的 APIs 來進行操作，以便達成更複雜的操作目的，這 Docuemnts 藉由 Swagger 等類似工具便可輕易產生線上即時的文件甚至是 API 的版本控管。

重新檢視軟體設計的基本原則

談到這裡，我們再來重新檢視所謂的的軟體架構設計、所謂的『模組化』是什麼？而所謂的軟體架構設計，關注的不外乎就是是『軟體元件』間的『組成』以及『架構』與『通訊』，設計軟體繪製 Domain Modeling 或是 UML 相關圖形為的是讓開發人員相互溝通，而程式碼 APIs 之間都溝通也是相同的道理。

所以 API 的設計的基礎原則來自於原始軟體設計，差異在於 API 的相互交流對象更廣，不只侷限在軟體分層架構內部、或是組織內部，也擴及到網路外部的開發者、各公司、供應商等，因此像是模組化、封裝、低耦合、高內聚等這些軟體設計的概念也完全適用於本章節所談的 API 設計。

API 的管理與開發的最佳實踐

圖（一）、API 開發的生命週期管理 

如圖（一）、API 的開發就等同於軟體開發，其開發也有其生命周期，API 的需求同樣需要被管理，從 API 的設計開始、開發、測試、佈署、維運、監控與異常處理、流量監測、直到安全控管、預防惡意攻擊等等，這些都屬於 API 的開發管理與實踐，這個 Topic 其實非常大，未來我在另闢一個文章來與各位探討。

下次...

下一篇，來與大家探討實務上如何透過 TDD 來驅動 API 的設計與開發，感謝大家！