前言

API 一開始通常都很單純。

前端要什麼，後端就回什麼。

但當系統開始被更多人使用，API 一旦改動，就可能影響既有前端、App、第三方串接，甚至是已經發布出去的舊版本程式。

這時候就會遇到一個問題：API 要怎麼改，才不會把舊使用者弄壞？

什麼情況會破壞相容性？

不是所有 API 修改都需要新版本。

例如新增一個 response 欄位，多數情況下不會破壞舊呼叫端：

1
2
3
4
5
{
  "id": 1,
  "name": "Hikari",
  "email": "hikari@example.com"
}

但以下這些改動就比較危險：

  • 移除既有欄位。
  • 改變欄位型別。
  • 改變欄位名稱。
  • 改變錯誤格式。
  • 改變必要參數。
  • 改變原本的業務規則。

例如原本 id 是數字：

1
2
3
{
  "id": 1
}

突然改成字串：

1
2
3
{
  "id": "U001"
}

對後端來說可能只是小改，但對呼叫端來說可能會直接壞掉。

常見版本寫法

最常見的方式是把版本放在 URL：

1
2
/api/v1/users
/api/v2/users

優點是直覺，看到網址就知道版本。

也有人會放在 header：

1
Accept: application/vnd.example.v2+json

這種方式比較乾淨，但對初學者或一般內部系統來說，URL 版本通常比較容易理解與維護。

不要太早過度設計

雖然 API versioning 很重要，但也不代表每個小專案一開始都要切很多版本。

如果系統只有自己使用，或還在快速開發期，過度設計版本反而會增加維護成本。

我覺得比較實際的做法是：

  • 先讓 API 格式一致。
  • 對外公開前想清楚 response 結構。
  • 有破壞相容性的改動時，再考慮新版本。
  • 舊版本保留一段過渡期。

版本控管是為了保護使用者，不是為了讓架構看起來很厲害。

結語

API 一旦被別人依賴，就不再只是後端自己家的事情。

每一次改動都要想：

  • 會不會讓舊呼叫端壞掉？
  • 是否需要保留舊版本？
  • 是否有清楚的遷移方式？
  • 文件是否同步更新？

好的 API 不只是能回資料，也要讓使用者能穩定地依賴它。