[ADP-41] API 版本控制

指導原則

必須(MUST)對外部受眾以上的 API 端點(即： audience≥PARTNET_EXTERNAL )的 API 端點進行版本控制。
INFO
關於 API 受眾請參照 ADP-752。
應(SHOULD)從常見的版本控制策略中選擇並詳細記錄。
- DRAFT 我們偏好使用 URI 版本控制，因為它在 URL 中非常清晰；但通過版本控制進行內容協商可能提供更多的可行性。
必須(MUST)使用語義化版本
應(SHOULD)盡量避免破壞性變更。
不應(SHOULD NOT)移除物件屬性，除非您已準備好增加主要版本號。
應(SHOULD)考慮同時支持新/舊版本的 API，對於外部受眾以上的 API 端點(即： audience≥PARTNET_EXTERNAL)。

API 版本控制有多種機制，每種都有其用例和優勢：

URL 版本控制
- 域名版本控制：這種方法涉及更改域名以反映版本。例如，api.v1.example.com 和 api.v2.example.com。此方法對主要版本變更有用，但可能會使 DNS 管理變得複雜並增加維護成本。
- URI 版本控制：這是一種常見方法，版本包含在路徑中。例如，example.com/api/v1/resource。它直觀且易於實施和理解。
基於查詢參數的版本控制
- 這種方法涉及在查詢字符串中添加版本參數。例如，example.com/api/resource?version=1。這對於可選版本控制和在不更改基礎 URL 的情況下測試新版本非常有用。
基於標頭的版本控制
- 版本資訊包含在 HTTP 標頭中。例如，添加自定義標頭 API-Version: 1。這種方法保持 URL 的清潔並且靈活，但可能對用戶和開發者不太可見。
基於資源（Content-Type, MIME）的版本控制
- 版本在 Content-Type 標頭中指定。例如，Content-Type: application/vnd.example.v1+json。這種方法對於同時支持多種內容類型和版本的 API 很有用。

基於語義版本：使用語義版本控制的主要和次要版本號，例如 v1 或 v1.1。
基於日期：使用日期來表示版本，例如 2024-07-08。
TIP
基於日期的版本控制仍然遵循語義版本控制原則。日期代表主要版本的發布日期，而不是 API 的修改日期。如果 API 發布不包括對其模式的破壞性變更，則日期版本值應保持不變。

請注意，版本控制策略可能會隨著 API 開發的成熟而變更。