F4 · Versioning API

F4 · Middle

Khi đổi ổ cắm điện mới, vẫn phải giữ ổ cũ cho các thiết bị cũ cắm được.

Cốt lõi

• Mục tiêu: tương thích ngược, không làm vỡ client hiện tại.
• URL: /v1/users vs /v2/users (phổ biến, rõ ràng, dễ cache/CDN).
• Header: Accept: application/vnd.api.v1+json. Query param: ?version=1.

Đánh đổi

URL rõ ràng nhưng "xấu" URI; Header gọn nhưng khó debug/cache.

Trong thực tế

Google Maps API dùng /v1, /v2.

Bug thường gặp

Đổi tên một trường trong JSON response → phiên bản app cũ mà người dùng chưa cập nhật bị lỗi.

Tự hỏi lại

Khi nào mới cần tăng version? Deprecate version cũ thế nào?