Trong một monorepo chứa cả ứng dụng web (Next.js) và ứng dụng di động (Expo/React Native), việc thay đổi API mà không có quy trình rõ ràng dễ dàng gây ra lỗi runtime trên một nền tảng trong khi nền tảng kia vẫn hoạt động bình thường. Dưới đây là một bộ thực hành đã được áp dụng thành công trong nhiều dự án thực tế. **1. Chọn chiến lược versioning phù hợp** - Version trong URL (ví dụ /api/v1/users) – dễ dàng route và cache. - Version qua header Accept (application/vnd.myapp.v2+json) – giữ URL gọn, phù hợp cho GraphQL. - Sử dụng Semantic Versioning (MAJOR.MINOR.PATCH) cho từng gói API nội bộ. **2. Xác định hợp đồng (contract) và test tự động** - Viết schema OpenAPI/GraphQL cho từng phiên bản. - Sử dụng Pact hoặc Schemathesis để chạy contract test trong CI mỗi khi có pull request. - Chặn merge nếu test thất bại, đảm bảo breaking change không lọt vào nhánh chính. **3. Chính sách depreciation rõ ràng** - Đánh dấu endpoint cũ với header Deprecation: true và Sunset: <ngày>. - Ghi log cảnh báo phía client (web hay mobile) khi gọi endpoint sắp bị xoá. - Cung cấp migration guide trong repo docs, kèm ví dụ code cho cả Next.js `fetch` và Expo `axios`. **4. Tách biệt lớp gọi API theo nền tảng** - Tạo thư viện shared `api-client` chứa các hàm gọi chung, nhận tham số `version`. - Web dùng `api-client/web.ts` (kết hợp với Next.js `getServerSideProps`), mobile dùng `api-client/mobile.ts` (kết hợp với React Query). - Khi cần nâng cấp phiên bản, chỉ cập nhật một nơi và chạy test contract. **5. Giám sát và rollback nhanh** - Đặt alert trên error rate theo version (Prometheus + Grafana). - Nếu phiên bản mới gây lỗi > 1% request, tự động rollback feature flag về phiên bản cũ. **Ví dụ thực tế**: Dự án có endpoint `/api/v1/orders`. Khi thêm trường `shippingAddress`, team tạo `/api/v2/orders` với schema mở rộng. Cả web và mobile cùng cập nhật `api-client` để mặc định gọi v2, nhưng vẫn giữ v1 hoạt động trong 30 ngày. Contract test chạy trên GitHub Actions phát hiện sớm việc thiếu trường bắt buộc, ngăn chặn deploy sai. Áp dụng các bước trên giúp nhóm phát triển tự tin triển khai tính năng mới mà không lo làm hỏng trải nghiệm người dùng trên bất kỳ nền tảng nào.