前言

API 並不是一成不變的，隨著需求與功能成長，API 經常需要 新增欄位、調整結構、甚至廢棄舊的設計。這時候，良好的 版本管理策略 就非常重要。

為什麼需要 API 版本管理？

如果我們沒有版本管理：

• 使用者的程式可能會因為 API 格式變動而 崩潰
• 無法同時維護「新功能」與「舊客戶端」
• 系統演進受到限制

有了版本管理，我們可以：

• 在不影響舊客戶端的前提下，推出新功能
• 明確告訴開發者哪個版本還能用
• 逐步淘汰舊版本

常見的 API 版本管理方法

方法一：URL 版本化（最常見）'

在路由中加入版本號：

GET /api/v1/users
GET /api/v2/users

• 優點：簡單直觀，容易理解
• 缺點：URL 會變長，每次更新都要改 endpoint

方法二：Header 版本化

透過 HTTP Header 傳遞版本號：

GET /api/users
Headers: 
  Accept: application/vnd.myapi.v1+json

• 優點：URL 乾淨，API 結構穩定
• 缺點：需要額外文件說明，不如 URL 明顯

方法三：Query Parameter

使用查詢參數指定版本：

GET /api/users?version=1

• 優點：容易快速實作
• 缺點：較少見，維護與一致性較差

如何決定要不要升版？

通常建議：

1. 相容性變更（Backward Compatible） -> 不需要升版

• 新增欄位（舊程式仍能正常運作）
• 提供新的可選參數

2. 不相容變更（Breaking Change） -> 需要升版

• 修改欄位名稱或刪除欄位
• 改變回傳結構
• 修改必填參數

Express API 的版本管理範例

import express from "express";
const app = express();

// v1 版本
app.get("/api/v1/users", (req, res) => {
  res.json([{ id: 1, name: "Alice" }]);
});

// v2 版本
app.get("/api/v2/users", (req, res) => {
  res.json([{ id: 1, username: "Alice", email: "alice@example.com" }]);
});

app.listen(3000, () => {
  console.log("API running on http://localhost:3000");
});

這樣我們就能同時維護 v1 與 v2，逐步引導使用者轉換。

API Deprecation（廢棄舊版本）

當舊版本 API 不再建議使用時，我們可以：

• 在 文件 中標註 Deprecated
• 在 回應 Header 中加入提醒：

Deprecation: true
Sunset: Wed, 01 Jan 2026 00:00:00 GMT

• 給開發者一段過渡時間，再正式下架

小結

• API 版本管理 能避免舊程式因更新而崩潰
• 常見方式： URL 版本化、Header 版本化、Query 參數
• Breaking Change -> 升版，相容性改動 -> 不升版
• 可以透過 Deprecation 機制 平滑過渡舊版本