Thiết kế API cho Mobile
Payload optimization, phân trang, và versioning API theo cách sống chung được với hàng triệu bản app cũ đang chạy ngoài kia.
Đây là module quan trọng nhất của cả khoá đối với vai trò Backend Engineer — API là điểm tiếp xúc trực tiếp và liên tục giữa công việc của bạn và trải nghiệm người dùng mobile. Thiết kế sai ở đây tạo ra hậu quả kéo dài hàng năm, vì không thể "ép" người dùng cập nhật app ngay lập tức.
🎯 Mục tiêu học tập
- Tối ưu payload API cho ràng buộc băng thông/pin của thiết bị di động
- Thiết kế phân trang (pagination) đúng cách cho danh sách dài trên mobile
- Áp dụng chiến lược versioning API sống chung được với nhiều phiên bản app cũ
- Thiết kế response format hỗ trợ tốt cả kịch bản online lẫn đồng bộ offline
Tối ưu Payload cho Ràng buộc Thiết bị Di động
- Chỉ trả về field client thực sự cần — không "tiện tay" trả cả object đầy đủ nếu màn hình danh sách chỉ hiển thị tên và ảnh đại diện; cân nhắc endpoint/field riêng cho danh sách (rút gọn) và chi tiết (đầy đủ).
- Ảnh: luôn trả về nhiều kích thước (thumbnail, medium, full) qua CDN, để client chọn đúng kích thước cần hiển thị — gửi ảnh gốc độ phân giải cao cho 1 avatar nhỏ lãng phí băng thông di động nghiêm trọng.
- Nén response: đảm bảo bật gzip/brotli ở tầng server/CDN — với kết nối di động, độ trễ và chi phí dữ liệu ảnh hưởng trực tiếp trải nghiệm hơn nhiều so với web trên Wi-Fi/cáp quang.
- GraphQL cho màn hình phức tạp: khi 1 màn hình cần dữ liệu từ nhiều nguồn khác nhau, GraphQL cho phép client lấy đúng-đủ dữ liệu trong 1 request thay vì nhiều lần gọi REST — cân nhắc kỹ đánh đổi độ phức tạp vận hành tăng thêm (đã bàn ở khoá System Architecture, Module 5).
Phân trang cho Danh sách dài
Offset-based pagination (?page=2&limit=20) đơn giản nhưng có vấn đề: nếu
dữ liệu thay đổi giữa các lần tải (có bản ghi mới được thêm/xoá), người dùng có thể thấy trùng lặp hoặc bỏ
sót khi cuộn — cursor-based pagination (?after=cursor_xyz&limit=20, dùng ID
hoặc timestamp làm điểm neo) ổn định hơn nhiều khi dữ liệu thay đổi liên tục, gần như luôn là lựa chọn
đúng cho feed/danh sách cuộn vô hạn (infinite scroll) — pattern UI phổ biến nhất trên mobile.
// Response mẫu hỗ trợ cursor pagination tốt cho infinite scroll
{
"items": [ ... ],
"next_cursor": "eyJpZCI6MTIzfQ==",
"has_more": true
}
Versioning API — sống chung với hàng triệu bản App cũ
Khác biệt căn bản với web (Module 1): không thể giả định mọi client đều gọi API bằng phiên bản mới nhất. Chiến lược thực tế:
| Chiến lược | Cách hoạt động | Đánh giá |
|---|---|---|
Version trong URL (/v1/, /v2/) | Route riêng biệt cho từng version lớn | Rõ ràng, nhưng duy trì nhiều version cùng lúc tốn công sức bảo trì kéo dài |
Header versioning (X-API-Version) | Client gửi kèm version trong header | Linh hoạt hơn URL, nhưng khó test/debug thủ công hơn |
| Additive-only + Feature flag theo Build Number | Chỉ thêm field mới (không xoá/đổi field cũ), backend kiểm tra build number của client để bật/tắt hành vi mới | Tránh được phần lớn nhu cầu version chính thức — nên là chiến lược mặc định |
Đổi kiểu dữ liệu 1 field, đổi tên field, hay xoá field mà không có giai đoạn chuyển tiếp có thể khiến app crash hàng loạt cho người dùng chưa cập nhật — khác hẳn web, không có cách nào "buộc" họ tải bản mới ngay lập tức. Luôn giữ field cũ hoạt động song song với field mới trong 1 khoảng thời gian đủ dài (thường vài tháng), theo dõi tỉ lệ request từ version cũ giảm dần trước khi thực sự deprecate.
Buộc Cập nhật App khi Thực sự Cần thiết
Khi có lỗ hổng bảo mật nghiêm trọng hoặc thay đổi không thể tương thích ngược, cần cơ chế force
update: API trả về 1 field báo hiệu (ví dụ {"min_supported_version": "3.2.0"}), app
kiểm tra và hiển thị màn hình bắt buộc cập nhật, chặn sử dụng tiếp cho đến khi người dùng tải bản mới từ
App Store/Google Play. Đây là "van an toàn cuối cùng" — nên thiết kế API tương thích ngược tốt (phần trên)
để hiếm khi phải dùng đến, vì force update luôn gây trải nghiệm khó chịu cho người dùng.
🏋️ Bài tập thực hành
Với 1 API danh sách bài viết hiện có (từ dự án ở khoá AI Engineer hoặc bất kỳ dự án nào của bạn), thiết kế lại theo đúng nguyên tắc: cursor-based pagination cho infinite scroll, response rút gọn cho danh sách (khác endpoint chi tiết), nhiều kích thước ảnh qua CDN. Viết ra chiến lược version cho API này nếu 6 tháng sau cần đổi cấu trúc dữ liệu 1 field quan trọng.
📚 Tài nguyên học tập
-
Stripe — API versioning approach (tham khảo thực hành tốt)Cách Stripe xử lý versioning API lâu dài, áp dụng được cho mobileBài viết
-
GraphQL — Official documentationTài liệu chính thức GraphQLDocs
✅ Tự đánh giá hoàn thành
- Áp dụng được các kỹ thuật tối ưu payload cho ràng buộc thiết bị di động
- Thiết kế đúng cursor-based pagination cho danh sách dài/infinite scroll
- Chọn đúng chiến lược versioning, ưu tiên additive-only trước khi cần version chính thức
- Thiết kế được cơ chế force update cho tình huống thực sự cần thiết