RESTful API 版本設計都在挑戰高穩定度和低介接維護門檻。這邊參考Stripe 的分享做以下整理。Stripe 是成長非常快速的金流公司,以API簡單易用為著名,所以API設計很具有參考價值。

一般版本控制最常利用的就是 v0, v1 的 URL prefix ,或是透過 Accept 的 HTTP 標頭來宣告,v0與v1裡小進版的API 就需要做到相容性的作業。不過反而導致客戶升級API的難度與意願增加,因為v0與v1間的改動都是較大的。Stripe 則另外使用日期做為 API 版本號,讓每次進版都是小幅度,藉此來減少維護進版的難度。

整理Strpe 版本設計上幾點做法:

  1. 使用Stripe-VersionHTTP 標頭,格式為日期,例如2017–05-24
  2. URL 一樣有 V0, V1,只是大部份時候並不會變動,所以 V1的版本下,可能有上百個不相容的日期版本
  3. 每個客戶可以於dashboard 設定預設 API version,或者會由第一次API call 來決定預設值

底層 API 實作面

  1. 使用 DSL 定義 API 的欄位。(猜測是 CI/CD automation或migrations時使用)
  2. 抽取 AbstractVersionChange,做為升級抽象模組,若有新 API 版本,則需實作,
  3. 在 VersionChange 中,定義版本號與對應的升級整合模組(Migration Module)
  4. 在 response 資料時,則會在 VersionChange中往舊版尋找至對應的版本,並依序執行升級Model(猜測是先 apply request 再 apply response 修改)
  5. 有可能有些版本相容實作較為複雜,會使用 has_side_effect annotation 但不做其他事,猜測用途是在其他程式(AbstractVersionChange)中,做例外判斷處理。當然這種弱封裝方式,也是儘量避免
  6. changelog 和 API Document的修改,這部份能用自動化程式依據DSL產生是最好做法

API進版原則

  1. Lightweight: 改變愈少愈好
  2. First-class: 在版本控制中為API中的first-class concept,方便docs 產生、tooling與changelog。
  3. Fixed-cost: 將舊API Migration程式碼,以最小的維護成本,封裝至VersionChange模組中。

原文參考資料:APIs as infrastructure: future-proofing Stripe with versioning

--

--

Virualization Code 網站是一個能將程式碼執行的每一步,電腦做的事用圖形展現出來。對於了解程式語言除了想像,能有實際圖像式的幫助理解。尤其對初學者練習程式思維很有幫忙。

Virualization Code有支援 Python, Java, C, C++, JavaScript, 和 Ruby。對老手,在釐清程式語言的基本的觀念,也能很直覺。

網站:http://pythontutor.com/

Virualization Code 讓你一步一步了解程式執行結果

--

--