Backend & APIHai cách phổ biến:
- URL path (/v1/orders) — Google API design guide và phần lớn API công khai chọn cách này. Dễ nhìn, dễ route, dễ cache, dễ chia traffic ở gateway. Nhược điểm: cùng một resource có nhiều URI.
- Header (Accept: application/vnd.api+json; version=2 hoặc header riêng như X-GitHub-Api-Version) — URI giữ nguyên, "thuần REST" hơn, nhưng khó test bằng trình duyệt và dễ bị quên khi cache.
Thực dụng: URL cho major version, header cho biến thể nhỏ. Đừng làm minor version (/v1.2) — không ai muốn sửa client vì một field mới.
Chỉ bump major khi có breaking change: xoá/đổi tên field, đổi kiểu dữ liệu, siết validation, đổi ngữ nghĩa field cũ, đổi mã lỗi. Thêm field mới, thêm endpoint, thêm giá trị enum optional → không cần version mới.
Quy trình deprecate an toàn:
1. Công bố lịch tắt kèm changelog và hướng dẫn migrate.
2. Trả header báo hiệu trên response của version cũ: Deprecation: true và Sunset: <ngày tắt> (RFC 8594), kèm Link: <docs>; rel="deprecation".
3. Theo dõi metric theo version + theo client để biết ai còn dùng, chủ động liên hệ.
4. Trước ngày tắt, chạy vài đợt brownout (cố tình trả lỗi trong khung giờ ngắn) để client phát hiện mình chưa migrate.
5. Tắt hẳn, trả 410 Gone kèm link tài liệu.
Chạy song song hai version tốn công bảo trì, nên đặt hạn rõ ràng ngay từ khi công bố.