Khi một ứng dụng đã có người dùng thật, việc sửa API không còn đơn giản là “đổi response rồi cập nhật frontend”. Có thể còn mobile app phiên bản cũ, đối tác đang tích hợp, hoặc một màn hình ít ai nhớ tới vẫn gọi endpoint cũ. API versioning giúp đội phát triển thay đổi hệ thống có kiểm soát, giảm nguy cơ làm hỏng các client đang hoạt động. Một ví dụ thực tế: ban đầu API trả thông tin người dùng như sau: GET /api/users/123 Response có field name là họ tên đầy đủ. Sau một thời gian, sản phẩm cần tách thành firstName và lastName để phục vụ tìm kiếm, cá nhân hóa email, sắp xếp danh sách. Nếu backend đột ngột bỏ name, các app cũ có thể hiển thị trắng hoặc lỗi. Cách an toàn hơn là tạo phiên bản mới: GET /api/v1/users/123 trả name GET /api/v2/users/123 trả firstName và lastName Như vậy, client mới dùng v2, client cũ vẫn chạy với v1 trong một khoảng thời gian chuyển tiếp. Một số cách versioning phổ biến: - Version trong URL: /api/v1/orders. Dễ nhìn, dễ debug, phù hợp với nhiều dự án. - Version trong header: Accept: application/vnd.app.v2+json. Gọn URL hơn nhưng khó quan sát hơn nếu không có công cụ tốt. - Version theo query: /api/orders?version=2. Dễ thử nghiệm nhưng thường kém rõ ràng nếu dùng lâu dài. Không phải thay đổi nào cũng cần tăng version. Thêm một field mới vào response thường là thay đổi tương thích, miễn là client không bị lỗi khi gặp field lạ. Nhưng đổi tên field, đổi kiểu dữ liệu, bỏ field, đổi ý nghĩa nghiệp vụ, thay format lỗi… thường là breaking change và nên được quản lý cẩn thận. Một vài lời khuyên có thể áp dụng: - Thiết kế client theo hướng chịu được thay đổi nhỏ: bỏ qua field không dùng, không phụ thuộc vào thứ tự field trong JSON. - Khi cần bỏ API cũ, hãy có thời gian deprecate rõ ràng: thông báo nội bộ, log client còn gọi v1, theo dõi traffic trước khi tắt. - Giữ tài liệu API theo từng version. Đừng để developer phải đoán endpoint nào còn dùng được. - Chuẩn hóa response lỗi giữa các version nếu có thể, vì frontend thường xử lý lỗi ở nhiều nơi. - Tránh tạo version mới cho từng thay đổi nhỏ. Quá nhiều version sẽ làm backend khó bảo trì. Một chiến lược tốt thường là: phát triển v2 song song với v1, cho client mới chuyển dần sang v2, theo dõi log để biết còn ai gọi v1, sau đó mới lên kế hoạch ngừng v1. Với mobile app, cần đặc biệt thận trọng vì người dùng không phải lúc nào cũng cập nhật ngay. API versioning không chỉ là đặt thêm “v1” hay “v2” vào đường dẫn. Nó là cách đội phát triển tôn trọng các client đang tồn tại, giúp sản phẩm tiến hóa mà không tạo ra sự cố không cần thiết. Nếu dự án bắt đầu có nhiều frontend, app mobile hoặc đối tác tích hợp, nên nghĩ đến versioning sớm thay vì chờ đến lúc một thay đổi nhỏ làm gãy cả hệ thống.