Không versioning API: Khi legacy sống hòa bình với tương lai

Không có v1/v2, nên giờ client cũ chạy sai thì… fix code client.

Khi audit một hệ thống backend, không ít lần tôi thấy API không có versioning. Mỗi lần thay đổi response, client cũ crash, team phải chạy đua fix cả backend lẫn client. Hệ thống như một bãi mìn: sửa gì cũng sợ “nổ”.

Khi backend phải phục vụ cả client cũ lẫn mới mà không versioning.

Vấn đề: Thay đổi response, client cũ chịu trận

Không versioning API nghĩa là tất cả client (web, mobile, third-party) đều gọi chung một endpoint. Khi bạn thêm field mới hoặc đổi format response, client cũ không biết, dẫn đến:

• Crash client: App mobile parse JSON lỗi, app dừng đột ngột.
• Hỗn loạn version: Team không biết client nào đang gọi version nào.
• Fix ngược đời: Phải viết code backend để hỗ trợ cả client cũ lẫn mới, làm code ngày càng rối.

Ví dụ: API /users ban đầu trả {name: "John"}, sau thêm age. Client cũ không xử lý age, parse lỗi, và thế là crash.

Giải pháp: Version hóa API

Để tránh hỗn loạn, hãy version hóa API ngay từ đầu:

1. Chọn cách version hóa:
• URL-based: /v1/users, /v2/users – đơn giản, dễ debug.
• Header-based: Dùng header Accept: application/vnd.api+json; version=1.0.
2. Document rõ ràng: Ghi trong API docs version nào deprecated, khi nào ngừng hỗ trợ.
3. Hỗ trợ song song: Giữ API cũ hoạt động trong thời gian chuyển đổi (thường 3-6 tháng).

Ví dụ: Nếu thêm field age vào /v1/users, tạo /v2/users với format mới, đồng thời giữ /v1/users cho client cũ.

🎯 Tóm lại: Versioning API giúp hệ thống linh hoạt, tránh phá vỡ client cũ. Hãy chọn cách version hóa phù hợp và document rõ ràng để cả team và client đều hiểu.