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