談API設計原則

當一位開發者在思考軟體設計時，腦中迸出的會是一堆類別、方法、函式、模組、資料庫等技術概念；而UML、流程圖、一堆框框和箭頭則用於協助我們理解程式的邏輯，不論是技術概念還是流程圖，我們在使用這些工具的同時實際上也是在進行一場彼此的溝通與交流。

同樣的，API的設計也是一種溝通，但不只是團隊內成員彼此的溝通，而是更大範圍的對外溝通，這些溝通我們又分成三個面向：

1. 網路面的溝通：API的設計過程中必然會涉及到通訊協議的選擇，而通訊協議的選擇對API的溝通效率有著顯著的影響，例如HTTP較適用於粗粒度的訊息交換，較不適合用於高密度通訊的場景，而像是MQTT（Message Queuing Telemetry Transport，訊息佇列遙測傳輸）則更適合細粒度的訊息交換，也就是高密度通訊場景。通訊協議影響了API的使用場景，我們在決定通訊協議時，應該要把應用場景中網路或設備可能會發生的效率問題也納入考量。

2. 開發者面溝通：對開發者而言，API的設計與文件就像是給他們的用戶介面，開發者透過文件才有辦法知道一支API的使用方式與時機，文件還能告訴開發者如何混搭不同的API操作，來達成更複雜的目的，對於開發者溝通，我們建議在API設計流程中盡早納入來自開發者的意見，才能設計出真正符合他們需求的API。

3. 市場面的溝通：透過API設計與文件，市場上的用戶、夥伴，以及開發人員才有辦法得知API具備那些數位能力，以及能幫他們達成什麼樣的目的，一個好的設計有助於API對市場面的溝通並促使人們善加利用他們。

如何建立有效的溝通，是從事API設計時的重要課題，而API設計流程能幫助我們去思考不同角度的溝通需求。

檢視軟體設計原則

所謂的軟體設計，關注的是軟體元件間的組成架構與通訊，而程式碼註解、時序圖（sequence diagram）、設計模式等，則是人們用於彼此溝通的工具，程式的通訊與人際的溝通，他們具有相同的本質。

API設計的基礎原則來自於軟體設計，差異在於API的交流對象更廣，不只侷限在組織內部，也擴及到外部的開發者，因此儘管模組化、封裝、低耦合、高內聚等這些軟體設計的概念也適用於API設計，開發者也早已熟悉，但下面我們會一一檢視將它們用於API設計時應額外考量的點。

模組化

「模組」是軟體程式中最小的構成單元，模組由一系列的類別、方法、函式所構成，模組可對外提供局部（local）、公開（public）的API，透過 API實現某些特定的機能或商業能力，模組有時也被稱為元件或函式庫。

大部分的程式語言都有提供模組化的特性，他們多半是用套件（package）或命名空間（namespace）來定義模組，當我們將那些彼此相關的程式碼歸納在同一個命名空間之下，這就是所謂的高內聚性（high cohesion），再透過程式語言的存取修飾器（access modifier）將模組內的實作細節隱藏起來。以Java 為例，它可以用public、protected、package、private這些關鍵字來設定一個模組的存取範圍，實現模組間的去耦合化（loose coopling）。

當許多的模組整合在一起，即成為一個系統，而子系統則是介於系統與模組間的單位，它也被視為一個整合了幾個相關模組的大模組。

模組與封裝的概念也同樣適用於Web API，它能幫助我們劃分每個API所擔負的功能，一方面確保了每支API的角色分明，一方面展現了API的數位能力，並且隱藏了內部細節，開發者將能更容易理解API，並且更快的對其上手。

封裝

封裝用於隱藏元件的內部細節，我們會用範圍修飾器（scope modifier）來限定一個模組可被存取的範圍，把一個有對外API的模組將內部細節隱藏起來，就算內部實作被修改，但只要不改變對外的API特性，任何依賴此API的外部程式就不會受到任何影響，有時我們將封裝稱為資訊隱藏。

封裝的概念在Web API被進一步的延伸，不僅是程式碼的實作細節被隱藏，包括Web框架、系統內的類別／物件、資料庫的設計等等也都被隱藏，形成更進一步的去耦合化，用戶只需要關心如何與API進行通訊，而不用去管API內部的那些實作細節，像是付款閘道內部是怎麼運作之類的，藉由封裝的機制，API用戶可以忽略那些內部細節，把心力投注在真正該重視的商業目標。

高內聚低耦合

內聚性（cohesion）指的是一個模組中的程式碼只與該模組內的其他程式碼有關，不與模組外的程式碼相關，以避免產生出俗稱「義大利麵」式盤根錯節、低內聚性的程式碼。

耦合性（coupling）是我們用來衡量模組間彼此獨立性的詞彙，高耦合的意思是兩個模組內的實作細節彼此高度依賴，反之低耦合指的是兩個元件的內部細節不互相依賴，彼此只透過外部的公開介面或程式語言的API溝通。

Web API延續了這樣的概念，在API設計上我們也會將相關性高的API操作群集起來，並把API與API間的內部細節封裝起來，形成高內聚、低耦合的架構。

Resource-Based API設計

數位世界的文件、圖像，或者實體世界的人員、物件，我們都可統稱為實體，而資源可以用於表示一個實體或是一系列實體的集合，每個資源都會被賦予特有的名稱或識別代號，而有時候資源也指涉商業流程、工作流程等更抽象的概念。

Resource-based API（以資源為基礎的API）關注的是網路兩端的資源互動行為，與內部的資料庫結構或程式物件無關，resource-based API為每種資源提供特定的資源行為，以及提供特定的格式，例如JSON或XML，讓外部程式，不論是Web app或手機app都能與資源進行互動。

資源≠資料模型

必須意識到的是，資源並不全然等於資料庫中的資料模型，資料庫的資料模型更著重在表達資料庫中的欄位、型別等資料結構上的規劃，以及讀寫效能、報表生產等的效率。

儘管資料也是API的一部分，但API設計中的資料不應該全盤照抄資料庫的資料規劃，資料庫的資料有它自己的特殊需求，例如讀寫效能、儲存最佳化、查詢效能等，著重的是更底層的效能考量。

如同人們對程式語言及框架的愛好不斷改變一般，人們對資料庫的選擇也不斷在變，一旦把API的資料直接取自底層的程式物件或資料庫，那麼一旦內部實作或欄位設計變更，那API的資料格式也必然得跟著變更，而這很有可能破壞既有的串接。

在Web API設計上，我們追求的是交付正確的結果、好的使用體驗、選擇適當的通訊協定、避免被特定語言綁定等，因為API涉及的是跨系統間的資料交換，它應該盡可能地使用固定的資料格式，而底層的資料模型缺不具備這樣的特性，他們很可能會隨著不同的取用需求而不斷增減。

雖然底層數據模型的決定的確可能會影響API的資料格式，但API在設計之時應盡量避免被特定的資料庫特性綁定。（摘錄整理自《Web API設計原則》第一章，碁峰資訊提供）

 書名  Web API設計原則：API與微服務傳遞價值之道

James Higginbotham／著

洪國梁／譯

碁峰資訊出版

定價：520元

 作者簡介 

圖片來源／James Higginbotham

James Higginbotham

James Higginbotham是開發者，也是架構師與顧問，在開發、部署應用程式、API等方面有超過25年的經驗，他的諮詢公司LaunchAny主要負責輔導企業數位轉型，經驗涵蓋銀行業、保險業、服務業、旅遊業以及航空業等，幫助企業將商業、產品、技術整合成模組化的架構，使企業成為可承載多元模組的戰略平台。