1. 18:35 13/10/2026
1. Tại sao cần versioning API?
- Khi sản phẩm phát triển, giao diện web và mobile thường chia sẻ cùng một backend. Thay đổi breaking change có thể làm hỏng một nền tảng mà không ảnh hưởng nền tảng kia.
- Versioning giúp nhóm frontend triển khai tính năng mới theo nhịp độ riêng, giảm rủi ro deploy.
2. Các chiến lược versioning phổ biến
- URL path versioning: /api/v1/users, /api/v2/users. Dễ thấy, dễ debug, phù hợp cho public API.
- Header versioning: Accept: application/vnd.myapp.v2+json. Giữ URL sạch, phù hợp khi muốn ẩn version khỏi log.
- Query param versioning: /api/users?version=2. Đơn giản nhưng dễ bị bỏ qua khi cache.
3. Nguyên tắc backward compatibility
- Không xóa field, chỉ thêm field mới (optional).
- Không thay đổi kiểu dữ liệu của field đã có (string → number).
- Luôn trả về default value cho field mới để client cũ không bị crash.
- Sử dụng deprecation header (Deprecation: true, Sunset: Sat, 01 Jan 2026 00:00:00 GMT) để thông báo thời hạn hỗ trợ.
4. Ví dụ thực tế với Node/Express và React
```js
// server/routes/users.js
app.get('/api/v1/users', (req, res) => {
const users = getUsers(); // [{id, name, email}]
res.json(users);
});
app.get('/api/v2/users', (req, res) => {
const users = getUsers().map(u => ({
...u,
profileUrl: `https://cdn.example.com/avatar/${u.id}.png` // field mới
}));
res.set('Deprecation', 'false');
res.json(users);
});
```
Trên client (React Web / React Native) dùng React Query:
```ts
const { data } = useQuery(['users', apiVersion], () =>
fetch(`/api/${apiVersion}/users`).then(r => r.json())
);
```
Khi cần nâng cấp, chỉ thay đổi biến `apiVersion` từ 'v1' sang 'v2' cho từng feature flag.
5. Quy trình phát hành an toàn
- Tạo branch release cho version mới, chạy test tự động cho cả web và mobile.
- Deploy version mới song song với version cũ (canary).
- Theo dõi metrics lỗi 4xx/5xx theo version qua logging (ELK, Datadog).
- Sau khi ổn định, cập nhật feature flag và thông báo sunset cho version cũ.
6. Lời khuyên áp dụng ngay
- Chọn URL path versioning cho API công khai, header versioning cho API nội bộ.
- Viết contract test (Pact) giữa frontend và backend cho mỗi version.
- Tự động sinh changelog từ commit message (Conventional Commits) để team frontend biết thay đổi gì.
- Đặt deadline sunset rõ ràng (ví dụ 6 tháng) và gửi email/notification cho team mobile/web.
Với cách tiếp cận này, cả React Web lẫn React Native đều có thể phát triển độc lập mà không lo bị phá vỡ khi backend thay đổi.