Cloud Native - API Design & Versioning

API Versioning

服務間依賴API溝通，但API versioning是一件不容易的事，有以下三種常見的approaches:

1. the knot - API版本永遠不更改（single version)，所以每次API更動，所有的clients都要更動

2. point-to-point - API提供者提供不同版本的API，client自己採用需要的版本，但是對API提供者來說維護成本高。

3. compatible versioning - API版本永遠不更改（single version)，但是向下相容，也是對API提供者較高的開發跟維護成本。

compatible versioning根據研究，會有較高的效率。

REST規格本身並沒有提供versioning規範，一般採用subdomain或是url path方式來區分不同version，例如

api-v1.test.com/users

./api/v2/users

另一種方式是mime-based approach，透過對header的resource version/type來標記API version，例如 (Accept: application/vnd.test.users.v2+json)，但是API url path並不會改變。

Backward Compatibility

對於採用compatible versioning approach來說，

上圖中，如果Service B v2.0要達成向下相容，代表他要能跟Service A v1.0能完全溝通，因為service A並不會有任何異動。要注意以下best practice來達成：

1. 新的API提供default values或是optional values，如果無法達成則應該要開新的API uri

2. 絕對不要重新命名或是移除現有的參數

3. 標記沒在使用的API endpoint obsolete

4. 同時測試新舊version API，傳舊的message data給兩者。

5. forward compatibility: 設計API時考慮未來相容性的話，implementation要能ignore新的參數，並不會出現任何錯誤！

Semantic Versioning

versioning的命名應該要有語意，讓人們能了解版本的差異 (major.minor.patch):

major - 當不相容的定義出現時，要增加major version

minor - 當向下相容的功能出現時，要增加minor version

patch - 當向下相容的bug fixes