---
# System prepended metadata

title: 第 11 章：在持續演變的園林中管理 API 週期
tags: [持續 API 管理]

---

###### tags: `持續 API 管理`
# 第 11 章：在持續演變的園林中管理 API 週期

## 實際管理不斷變化的園林
這章節我們嘗試將前面章節建立的園林「宏觀」模型與「微觀」模型做結合，但結合前先探討三種幫你管理園林的做法

1. 將你的「紅線」社會化
+ 明確定義那些沒得商量、風險太高、阻礙商業目標的事情
+ 明確定義原則、政策，甚至是「Best Practice」
+ 例如：
  + 服務不可中斷
  + 不可使用 X 公司工具
  + 不能違反政府法令
  + 不可使用外部第三方工具 

2. 平台大於專案（最終）
+ API 園林如果沒有持續進步，公司很難獲得最大的利益，但問題在於追求持續進步的方式
+ 專案思維：成立專案小組進行短期改善
  + 高效、可衡量且可管理
  + 專案結束後有可能變成孤兒，沒有當責的對象
+ 平台思維：建立一永續團隊持續改善維護
  + 必須獲得組職的資金與信任
  + 轉換為平台思維，告訴公司你的平台是能夠提供價值的，並對營運提出建議

這兩個方法都不完美，因採取切合實際的狀況，但經驗告訴我們平台思維更適合組織
   
3. 為消費者、生產者和贊助者設計
無論是產品還是平台，成功都取決於滿足用戶需求。在 API 園林裡，你要迅速釐清誰是系統的主要消費者、生產者和贊助者

+ 服務你的消費者
  + 思考哪一支 API 對開發者最重要
+ 服務你的生產者
  + 以平台觀點來看，思考哪個服務對建構和運行 API 的團隊最重要
+ 服務你的贊助者
  + 思考 API 園林怎樣設計更容易被贊助人理解與觀察，以助於永續發展(資金)

## 測試、衡量與學習
在處理大型問題時，我們常常進行小改變，並從中學習。我們稱之為「測試並學習」。

下列因素將決定你啟動 API 園林的方式
+ 組織目標
+ 「紅線」
+ 使用的技術及人員

例如：
+ 「綠地」的有機園林演進
  1. 啟動 API 產品開發
  2. 成立一個跨產品的 API 專家團隊
  3. 汲取個別 API 的經驗教訓和最佳功能，將它們做成園林級的功能
  4. 賦予 API 專家權力，將園林功能帶回他們的 API 產品中

+ 「棕地」的結構化園林演進
  1. 確認將會因為改進而受益的候選 API
  2. 建立營運措施和 KPI 來衡量進度
  3. 實施園林級的策略，並用候選 API 進行測試
  4. 觀察衡量結果，並對園林進行調整
  5. 向更多 API 推出園林級的策略

採取「測試、衡量與學習」，才能讓演化的過程變得更好。定義好的衡量指標並不容易，幸好你可以參考前面章節提到的 8 個 V 以及 API 產品支柱。

### 決策點與成熟度
按照經驗法則，「晚一點」做決定往往是明智的選擇，但最 後的決定時間點總是困難的

## 園林層面與 API 生命週期支柱
隨著 API 生態系統成長，你會加入更多團隊，產生不同的目標，遇到各式各樣可能的情況。園林不只是變大而已，也可能**改變形狀**。
因此最後，我們用一個簡單的表格，結合 API 生命週期支柱與園林層面來了解你需要在 API 生態系統中管理的領域。

### 策略
隨著 API 園林成長，策略隨時會調整，例如 KPI 可能會從一開始衡量可靠性，轉變為使用量、收益等等。這時有三個面向要特別注意：多樣性、數量、速度
+ 多樣性：隨著園林成長，去限制多個團隊（甚至是分散在全球各地）採用同樣的設計規範、工具、開發方法是不切實際的。這時應嘗試訂定==基本原則==讓全團隊遵守，並接受差異，保持健康的多樣性。
+ 數量
  + 隨著園林成長，應把重心放在明顯帶來業務 API，以及讓 API 更容易被更新與維護。
  + 高流量時，是否容易水平擴展，是否上雲、On-Premise 或是使用 FaaS 都是選項之一
+ 速度
  + 隨著需求變化越來越快，必須做好==變動管理==降低風險
  + 變動快速時，API 策略也必須適時調整，例如公司開始進入成長期，前台大量接訂單，但後台仍採用人工作業，容易讓公司暴露在高風險底下

### 設計
介面設計是 API 產品工作的重要支柱，有時是單獨使用，有時則必須與其他 API 搭配使用。這時有三個面向對設計支柱有最大的影響力：多樣性、詞彙、版本系統
+ 多樣性：隨著時空背景不同會採用不同做法來解決同樣的問題，因此可以適度的允許多樣性，但必須要有充足的理由，否則反而容易產生負面影響。
+ 詞彙：統一詞彙對 API 設計是件好事
+ 版本系統：新版本通常代表用新方法解決問題。此時公司應公開，並隨時讓使用者了解新版本，但只有使用者要使用新版本時才要求使用者做一些事。

### 文件
+ 多樣性：允許團隊討選當下最好的文件風格
+ 詞彙：為這些詞彙管理文件，讓使用詞彙的 API 都可以連到該詞彙的文件
+ 版本系統：紀錄歷史也是 API 的一部分，讓使用者了解 API 的演進歷史
+ 能見度：文件有許多內容與結構，有可能相當複雜，可以適時提供深層連結，來提升整體能見度

### 開發
+ 多樣性：沒有一套方法與程式語言能保證用來開發 API 是最好的，讓團隊覺得可以「實驗」新方法，保持多樣性是重要的。並視狀況將「實驗」轉為「實作」
+ 速度：語言、工具、部署、社群大小
+ 版本系統：提供版本資訊 (LTS)、公開版本號，並盡量降低新版本的負面影響
+ 易變性：必須考慮服務不穩定的狀況該如何處理

備註：GraphQL 與 API 的可用性

### 測試
隨著 API 園林成長，時程壓力，測試寫不寫、測不測都是問題。這時可以從以下 4 個方向去思考
+ 數量
  + 導入自動化測試取代部分 QA loading
  + 視流量調整壓力測試等級
+ 速度：隨著生態系統成長，測試速度可能越來越慢
  + 測試經驗法則
    + 單元測試：幾秒內完成
    + 行為或商業測試：不超過 30 秒
    + 整合測試：不超過 5 分鐘
  + 改善方式
    + 平行測試
    + 虛擬化 (replay)
    + 金絲雀（尋找 beta 測試者）
    + 只測試關鍵流程相關測試
+ 漏洞：「所有服務介面在一開始就必須設計成可以開放給外人使用」
+ 易變性：API 園林當中若有一個節點出問題可能會造成大影響（例如熱門函式庫出現漏洞）針對關鍵元件務必測試這樣的狀況，並寫程式來處理。

### 部署
+ 多樣性：自動化部屬應盡量避免多樣性，限制變化
+ 速度：將自動化範圍擴大提升速度
  + 第 1 型：尋找減少「回饋到實現」次數的方式
  + 第 2 型：多個團隊同時發表
+ 版本系統：語義版本模式（MAJOR.MINOR.PATCH.RELEASE)
+ 易變性：增加部署速度，容易增加易變性風險，這時可以嘗試做三件事
  + 確保釋出版本沒有破壞性變更
  + 維護穩定性始終一致的套件
  + 支援隨時可逆的安裝 (rollback, feature toggle)

### 安全防護
+ 速度
  + 確保所有人都有基本資安知識，以安全的方式設計與建構元件
  + 自動化安全測試（如滲透測試）
+ 漏洞：API 數量成長，漏洞數量也跟著成長。除了加入安全測試之外，讓專責資安的部門及負責的團隊都分擔資安的loading。
+ 能見度
  + 零信任
  + Dashboard -> Trend
  + Log -> Analysis

### 監控
+ 數量
  - 將責任下放到各個團隊
  - 不只監控單一 API，也監控元件互動
  - 建立中央資料庫，重心放在各種 API 之間的關聯
  - 找出正常與異常的 pattern 用以解決問題
+ 能見度
  - 記錄每件事，並且只監控選定的資料集合
  - 中央單位 overview 管控，團隊較 detail 的管控
+ 易變性
  - 較大型系統有較高的易變性
  - 需要可靠的監控系統降低高易變性的風險（一個 bug 搞壞整個系統）

### 發現
+ 多樣性：API 文件可以很多形式出現，在必要時可被加強或替換。
+ 數量：不但要協助使用者找到 API，也要進行排序（如實用性排名）。當然，排名也會隨時空背景而改變
+ 詞彙：可以在 API 園林建立類似 schema.org 原則，適時給予標記，甚至可以要求團隊一定要加上這資訊
+ 能見度：從小事做起，並不斷發展成更大的資訊集合，並在 API 揭露
+ 版本系統：紀錄 API 所有版本，並提供給使用者查閱，可能讓這 API 更容易被發現

### 變動管理
盡量減少對 API 生態系統的破壞，有兩種方法
1. 遵守變動規則，根據特定模式進行安全變更
2. 不改變已發表 API，同時運作多個版本

+ 詞彙：詞彙更新會導致 API 更新。當然詞彙也可以與 API 解耦（概念類似 i18n），使 API 在詞彙改動時維持穩定
+ 速度：好的變動管理對速度有直接關係
+ 版本系統：語義版本系統
  + Patch: 功能不變，修 bug
  + Minor: 可回溯相容，若已滿足需求則可忽略
  + Major: 有破壞性變動，需告知目前版本多久後移除
+ 能見度：一般用戶在需要新功能時，才會配合改變後的 API，這時變動管理的能見度就很重要了，而語義版本系統可幫助提升能見度。