Phiên bản API cho ứng dụng di động: tiến hóa các điểm cuối một cách an toàn

Tại sao thay đổi API làm người dùng di động bị ảnh hưởng

Ứng dụng di động không cập nhật cùng lúc. Dù bạn phát hành bản sửa hôm nay, nhiều người vẫn sẽ dùng bản cũ trong vài ngày hoặc vài tuần. Một số tắt cập nhật tự động. Một số thiếu dung lượng. Một số khác đơn giản là ít mở app. Thời gian duyệt app store và staged releases còn tạo ra thêm độ trễ.

Khoảng cách này quan trọng vì backend thường thay đổi nhanh hơn client di động. Nếu server thay đổi một endpoint và app cũ vẫn gọi nó, app có thể hỏng mặc dù điện thoại của người dùng không thay đổi.

Sự hỏng hiếm khi hiện ra như một thông báo lỗi rõ ràng. Thường nó là những vấn đề sản phẩm hàng ngày:

• Đăng nhập hoặc đăng ký thất bại sau khi backend được cập nhật
• Danh sách trông trống vì một trường bị đổi tên hoặc chuyển chỗ
• App crash khi đọc một giá trị bị thiếu
• Thanh toán thất bại vì validation bị thắt chặt
• Tính năng biến mất lặng lẽ vì cấu trúc response thay đổi

Mục đích của versioning đơn giản: tiếp tục cải tiến server mà không buộc mọi người phải cập nhật ngay lập tức. Hãy coi API như một hợp đồng lâu dài. Phiên bản app mới nên hoạt động với hành vi server mới, và các phiên bản cũ nên tiếp tục hoạt động đủ lâu cho chu kỳ cập nhật thực tế.

Với hầu hết app người tiêu dùng, hãy kỳ vọng phải hỗ trợ nhiều phiên bản app cùng lúc. Ứng dụng nội bộ có thể tiến nhanh hơn, nhưng hiếm khi tức thì. Lập kế hoạch cho sự chồng lấn giúp rollout theo giai đoạn diễn ra suôn sẻ thay vì biến mỗi release backend thành cơn bão support.

“Tương thích” nghĩa là gì với hợp đồng API

Hợp đồng API là lời hứa giữa app di động và server: URL gọi tới, input chấp nhận, response trông thế nào và ý nghĩa của từng trường. Khi app dựa vào lời hứa đó và server thay đổi nó, người dùng sẽ cảm nhận bằng crash, dữ liệu thiếu, hoặc tính năng không hoạt động.

Một thay đổi là tương thích khi các phiên bản app cũ vẫn có thể dùng API mà không cần sửa mã. Thực tế, điều đó có nghĩa là server vẫn hiểu những gì app cũ gửi và vẫn trả về response mà app cũ có thể parse.

Một cách nhanh để phân tách thay đổi an toàn và rủi ro:

• Breaking changes: xoá hoặc đổi tên trường, đổi kiểu (số -> chuỗi), biến trường tùy chọn thành bắt buộc, thay đổi định dạng lỗi, thắt chặt validation theo cách mà app cũ không đáp ứng được.
• Thay đổi thường an toàn: thêm trường tùy chọn mới, thêm endpoint mới, chấp nhận cả định dạng request cũ và mới, thêm giá trị enum mới (miễn là app xử lý giá trị lạ như “other”).

Tính tương thích cũng cần kế hoạch kết thúc vòng đời. Việc huỷ bỏ hành vi cũ là hợp lý, nhưng cần được lên lịch (ví dụ: “giữ v1 trong 90 ngày sau khi v2 phát hành”) để bạn có thể tiến hoá mà không làm người dùng bất ngờ.

Các cách tiếp cận versioning phổ biến và đánh đổi

Versioning là về việc giữ hợp đồng ổn định cho các build cũ trong khi bạn tiến lên. Có vài cách phổ biến, và mỗi cách đẩy sự phức tạp về một chỗ khác nhau.

Version theo URL

Đặt phiên bản trong đường dẫn (ví dụ /v1/ và /v2/) dễ nhìn và dễ debug. Nó cũng hoạt động tốt với caching, logging và routing vì phiên bản nằm trong URL. Nhược điểm là các team có thể phải duy trì handlers song song lâu hơn cả khi khác biệt nhỏ.

Version qua header

Với header versioning, client gửi phiên bản trong header (ví dụ header Accept hoặc header tuỳ chỉnh). URL gọn hơn và bạn có thể tiến hóa API mà không thay đổi mọi path. Nhược điểm là tính hiển thị: proxies, logs và con người thường bỏ qua header trừ khi bạn cẩn thận, và client di động phải chắc chắn gửi header ở mọi request.

Version theo query parameter

Query versioning (như ?v=2) trông đơn giản nhưng dễ rối. Tham số bị sao chép vào bookmark, công cụ analytics và script, và bạn có thể có nhiều “phiên bản” lang thang mà không rõ người chịu trách nhiệm.

So sánh đơn giản:

• URL versioning: dễ kiểm tra, nhưng có thể tạo API song song tồn tại lâu
• Header versioning: URL sạch, nhưng khó troubleshoot hơn
• Query versioning: khởi động nhanh, dễ bị dùng sai

Feature flags là một công cụ khác. Chúng cho phép bạn thay đổi hành vi sau cùng cùng hợp đồng (ví dụ thuật toán xếp hạng mới) mà không tạo phiên bản API mới. Chúng không thay thế versioning khi dạng request/response phải thay đổi.

Chọn một cách và nhất quán. Tính nhất quán quan trọng hơn “lựa chọn hoàn hảo”.

Quy tắc tổng quát cho thay đổi tương thích ngược

Tư duy an toàn nhất là: client cũ nên tiếp tục hoạt động ngay cả khi không biết đến tính năng mới. Điều đó thường có nghĩa là thêm chứ không phải đổi những gì đã tồn tại.

Ưu tiên các thay đổi bổ sung: trường mới, endpoint mới, tham số tùy chọn mới. Khi thêm, hãy thực sự làm cho nó tùy chọn từ phía server. Nếu app cũ không gửi, server nên hành xử y hệt trước đó.

Một vài thói quen giúp tránh hỏng hóc:

• Thêm trường, nhưng không đổi kiểu hay ý nghĩa của trường hiện có.
• Xử lý input thiếu như bình thường và dùng mặc định hợp lý.
• Bỏ qua các trường request không nhận diện để client cũ và mới cùng tồn tại.
• Giữ định dạng lỗi ổn định. Nếu phải đổi, hãy phiên bản hoá payload lỗi.
• Nếu hành vi phải thay đổi, giới thiệu endpoint mới hoặc bump version thay vì “sửa lén”.

Tránh đổi ý nghĩa của một trường hiện có mà không có version bump. Ví dụ, nếu status=1 trước đây nghĩa là “paid” và bạn tái sử dụng thành “authorized”, app cũ sẽ đưa ra quyết định sai và bạn có thể không nhận ra cho đến khi người dùng phàn nàn.

Đổi tên và loại bỏ cần kế hoạch. Mẫu an toàn nhất là giữ trường cũ và thêm trường mới song song trong một thời gian. Điền cả hai trong response, chấp nhận cả hai trong request, và log ai còn đang dùng trường cũ. Chỉ xóa trường cũ khi cửa sổ deprecation kết thúc.

Một thói quen nhỏ nhưng mạnh: khi bạn đưa ra quy tắc nghiệp vụ mới bắt buộc, đừng yêu cầu client chịu trách nhiệm ngay ngày đầu. Hãy đặt quy tắc trên server với mặc định trước, rồi sau đó yêu cầu client gửi giá trị mới khi hầu hết người dùng đã cập nhật.

Đặt chính sách versioning và deprecation đơn giản

Versioning hiệu quả khi các quy tắc nghèo nàn nhưng được viết ra. Giữ chính sách đủ ngắn để product, mobile và backend team thực sự theo.

Bắt đầu với cửa sổ hỗ trợ. Quyết định sẽ giữ các phiên bản API cũ chạy bao lâu sau khi phiên bản mới ra mắt (ví dụ 6–12 tháng), và các ngoại lệ (vấn đề bảo mật, thay đổi pháp lý).

Tiếp theo, định nghĩa cách bạn cảnh báo client trước khi phá vỡ. Chọn một tín hiệu deprecation và dùng nó mọi nơi. Các tùy chọn phổ biến bao gồm header response như Deprecation: true kèm ngày nghỉ hưu, hoặc một trường JSON như "deprecation": {"will_stop_working_on": "2026-04-01"} trên một số response được chọn. Điều quan trọng là tính nhất quán: client có thể phát hiện, dashboard báo cáo, và support explain được.

Đặt phiên bản app tối thiểu được hỗ trợ, và rõ ràng về cách thực thi. Tránh block bất ngờ. Cách thực tế:

1. Trả về cảnh báo mềm (ví dụ một trường kích hoạt prompt cập nhật trong app).
2. Chỉ thực thi sau hạn chót đã thông báo.

Nếu bạn chặn request, trả lỗi rõ ràng với thông điệp thân thiện và mã máy dễ đọc.

Cuối cùng, quyết định ai được duyệt breaking change và tài liệu cần có. Giữ đơn giản:

• Một người chủ duyệt breaking change.
• Một ghi chú ngắn giải thích thay đổi, ai bị ảnh hưởng và đường di cư.
• Kế hoạch test bao gồm ít nhất một phiên bản app cũ.
• Ngày nghỉ hưu được đặt khi bắt đầu deprecation.

Kế hoạch rollout theo bước để giữ app cũ hoạt động

Người dùng di động không cập nhật trong ngày đầu. Cách an toàn là phát hành API mới trong khi để API cũ nguyên vẹn, rồi chuyển traffic dần dần.

Đầu tiên, xác định v2 thay đổi gì và khoá hành vi v1. Xử lý v1 như một lời hứa: cùng trường, cùng ý nghĩa, cùng mã lỗi. Nếu v2 cần dạng response khác, đừng sửa v1 để khớp v2.

Tiếp theo, chạy v2 song song. Điều này có thể là routes riêng (như /v1/... và /v2/...) hoặc handlers riêng sau gateway. Giữ logic chung ở một chỗ, nhưng tách hợp đồng để refactor v2 không vô tình thay đổi v1.

Rồi cập nhật app để ưu tiên v2. Xây một fallback đơn giản: nếu v2 trả “not supported” (hoặc lỗi biết trước), thử lại v1. Điều này giúp trong staged releases và mạng thực tế lộn xộn.

Sau khi phát hành app, giám sát adoption và lỗi. Các kiểm tra hữu ích bao gồm:

• Lưu lượng request v1 vs v2 theo phiên bản app
• Tỷ lệ lỗi và latency cho v2
• Lỗi parse response
• Crash liên quan màn hình mạng

Khi v2 ổn, thêm cảnh báo deprecation cho v1 và thông báo timeline. Chỉ retire v1 khi usage giảm xuống ngưỡng chấp nhận được (ví dụ dưới 1–2% trong nhiều tuần).

Ví dụ: bạn thay GET /orders để hỗ trợ filter và trạng thái mới. v2 thêm status_details còn v1 giữ nguyên. App mới gọi v2, nhưng nếu gặp edge case nó fallback về v1 và vẫn hiển thị danh sách đơn.

Mẹo triển khai phía server

Hầu hết lỗi rollout xảy ra vì xử lý phiên bản rải rác trong controllers, helpers và database. Giữ quyết định “request thuộc phiên bản nào?” ở một chỗ, và làm cho phần còn lại logic có thể dự đoán được.

Đặt routing phiên bản sau một cổng duy nhất

Chọn một tín hiệu (URL segment, header, hoặc app build number) và chuẩn hoá sớm. Route đến handler đúng trong một module hoặc middleware để mọi request theo cùng đường đi.

Một pattern thực tế:

• Parse phiên bản một lần (và log nó).
• Map phiên bản tới handler (v1, v2, ...) trong một registry.
• Giữ utilities dùng chung không phụ thuộc phiên bản (parse ngày, auth checks), không giữ logic hình dạng response.

Cẩn thận khi chia sẻ code giữa các phiên bản. Sửa bug v2 trong code “chung” có thể vô tình thay đổi hành vi v1. Nếu logic ảnh hưởng tới trường output hoặc rules validation, phiên bản hoá nó hoặc cover bằng test theo phiên bản.

Giữ thay đổi dữ liệu tương thích trong rollout

Migration database phải hoạt động cho cả hai phiên bản cùng lúc. Thêm cột trước, backfill nếu cần, và chỉ sau đó mới xóa hoặc thắt chặt ràng buộc. Tránh đổi tên hoặc thay đổi ý nghĩa giữa rollout. Nếu cần chuyển định dạng, cân nhắc viết cả hai định dạng trong một thời gian ngắn cho tới khi client cập nhật.

Làm cho lỗi dễ đoán. App cũ thường coi lỗi không biết là “có gì đó sai”. Dùng mã trạng thái nhất quán, định danh lỗi ổn định, và thông điệp ngắn giúp client quyết định (thử lại, re-auth, hiển thị prompt cập nhật).

Cuối cùng, phòng trường hợp client không gửi trường mà app cũ không có. Dùng mặc định an toàn và validate với chi tiết lỗi rõ ràng, ổn định.

Những lưu ý phía mobile ảnh hưởng tới versioning

Vì người dùng có thể ở bản build cũ hàng tuần, versioning phải giả định nhiều phiên bản client cùng gọi server đồng thời.

Một chiến thắng lớn là chịu đựng ở phía client. Nếu app crash hoặc parse lỗi khi server thêm trường, bạn sẽ gặp lỗi rollout “ngẫu nhiên”.

• Bỏ qua trường JSON lạ.
• Xử lý trường thiếu như bình thường và dùng mặc định.
• Xử lý null an toàn (trường có thể trở nên nullable khi migration).
• Không phụ thuộc vào thứ tự mảng trừ khi hợp đồng đảm bảo.
• Giữ xử lý lỗi thân thiện với người dùng (trạng thái retry tốt hơn màn hình trắng).

Hành vi mạng cũng quan trọng. Trong rollout bạn có thể tạm thời có nhiều phiên bản server sau load balancer hoặc cache, và mạng di động khuếch đại vấn đề nhỏ.

Chọn timeout và retry rõ ràng: timeout ngắn cho read call, dài hơn chút cho upload, và retry giới hạn với backoff. Làm idempotency chuẩn cho các call tạo hoặc thanh toán để retry không gây gửi kép.

Thay đổi auth là cách nhanh nhất khoá app cũ. Nếu đổi format token, scope bắt buộc, hoặc rule session, giữ cửa sổ chồng lấp để cả token cũ và mới cùng hợp lệ. Nếu phải rotate key hoặc claim, lên kế hoạch migration theo giai đoạn, không cắt toàn bộ cùng một ngày.

Gửi metadata app cùng mỗi request (ví dụ app version và platform). Điều này giúp trả cảnh báo theo mục tiêu mà không cần tách toàn bộ API.

Giám sát và rollout theo pha không bất ngờ

Rollout theo pha chỉ hoạt động nếu bạn thấy được phiên bản app khác nhau đang làm gì. Mục tiêu: biết ai còn dùng endpoint cũ, và bắt vấn đề trước khi tới mọi người.

Bắt đầu bằng việc track usage theo phiên bản API mỗi ngày. Đừng chỉ đếm tổng request. Track device active, và phân tích các endpoint quan trọng như login, profile, payments. Điều này cho biết phiên bản cũ có thực sự “sống” không dù traffic tổng thể nhỏ.

Rồi theo dõi lỗi theo phiên bản và loại. Tăng 4xx thường báo mismatch hợp đồng (trường bắt buộc đổi, enum lệch, auth thắt chặt). Tăng 5xx thường chỉ server regressions (deploy xấu, truy vấn chậm, dependency fail). Nhìn cả hai theo phiên bản giúp bạn chọn fix đúng nhanh.

Dùng staged rollout trên app store để giới hạn blast radius. Tăng phạm vi theo bước và quan sát cùng dashboard sau mỗi bước (ví dụ 5%, 25%, 50%). Nếu bản mới gặp vấn đề, dừng rollout trước khi trở thành outage toàn bộ.

Có triggers rollback ghi sẵn trước, đừng quyết định trong sự cố. Triggers phổ biến:

• tỷ lệ lỗi vượt ngưỡng trong 15–30 phút
• tỷ lệ login giảm hoặc token refresh fail tăng
• thanh toán thất bại tăng hoặc timeout checkout tăng
• spike ticket support liên quan phiên bản cụ thể
• latency tăng trên endpoint quan trọng

Giữ playbook sự cố ngắn cho outage liên quan phiên bản: ai phải được paging, cách tắt flag rủi ro, release server để rollback, và cách kéo dài cửa sổ deprecation nếu client cũ vẫn hoạt động.

Ví dụ: tiến hoá một endpoint trong release thật

Checkout là thay đổi thực tế điển hình. Bạn bắt đầu với flow đơn giản, sau đó thêm bước thanh toán mới (như xác thực mạnh hơn) và đổi tên trường để phù hợp ngôn ngữ nghiệp vụ.

Giả sử mobile gọi POST /checkout.

Những gì giữ ở v1 và gì thay đổi ở v2

Ở v1, giữ request và hành vi hiện tại để các bản app cũ hoàn thành thanh toán không bị bất ngờ. Ở v2, giới thiệu flow mới và tên trường rõ ràng hơn.

• v1 giữ: amount, currency, card_token, và response đơn như status=paid|failed.
• v2 thêm: payment_method_id (thay card_token) và một trường next_action để app xử lý bước tiếp theo (verify, retry, redirect).
• v2 đổi tên: amount -> total_amount, currency -> billing_currency.

App cũ vẫn hoạt động vì server áp mặc định an toàn. Nếu request v1 không biết next_action, server hoàn tất thanh toán khi có thể và trả kết quả dạng v1. Nếu bước mới bắt buộc, v1 nhận mã lỗi rõ ràng như requires_update thay vì lỗi mơ hồ.

Adoption, retirement và rollback

Theo dõi adoption theo phiên bản: tỉ lệ checkout gọi v2, tỷ lệ lỗi, và bao nhiêu user còn chạy build chỉ hỗ trợ v1. Khi v2 ổn định cao (ví dụ 95%+ vài tuần) và v1 ít dùng, chọn ngày nghỉ v1 và thông báo (release notes, in-app messaging).

Nếu có vấn đề sau launch, rollback nên nhàm chán:

• Route nhiều traffic về hành vi v1 hơn.
• Tắt bước thanh toán mới bằng flag server-side.
• Tiếp tục chấp nhận cả hai bộ trường và log những gì bạn phải auto-convert.

Sai lầm phổ biến dẫn tới hỏng lặng lẽ

Hầu hết lỗi API di động không ầm ĩ. Request vẫn thành công, app vẫn chạy, nhưng người dùng thấy dữ liệu thiếu, tổng tiền sai, hoặc nút bấm không hoạt động. Những lỗi này khó phát hiện vì thường chỉ ảnh hưởng app cũ trong rollout theo pha.

Nguyên nhân phổ biến:

• Đổi hoặc xoá trường (hoặc đổi kiểu) mà không có kế hoạch version rõ ràng.
• Yêu cầu trường mới ngay lập tức, khiến app cũ bị từ chối.
• Migration database giả định chỉ có app mới.
• Nghỉ v1 dựa trên số lượt cài đặt, không phải sử dụng thực tế.
• Quên các background job và webhook vẫn gọi payload cũ.

Ví dụ cụ thể: field total trước là chuỗi ("12.50") bạn đổi thành số (12.5). App mới ok. App cũ có thể coi nó là 0, ẩn nó, hoặc crash trên một số màn hình. Nếu bạn không xem lỗi client theo phiên bản, nó dễ lọt qua.

Checklist nhanh và bước tiếp theo

Versioning ít về đặt tên endpoint khéo và nhiều về lặp lại cùng các kiểm tra an toàn ở mỗi release.

Kiểm tra nhanh trước release

• Giữ thay đổi mang tính bổ sung. Không xoá hay đổi tên trường mà app cũ đọc.
• Cung cấp mặc định an toàn để trường mới thiếu vẫn như luồng cũ.
• Giữ response lỗi ổn định (status + shape + meaning).
• Cẩn trọng với enum và không đổi ý nghĩa giá trị hiện có.
• Replay vài request thực từ các phiên bản app cũ và xác nhận response vẫn parse được.

Kiểm tra nhanh trong rollout và trước khi retire

• Track adoption theo phiên bản app. Muốn thấy đường cong rõ từ v1 sang v2, không phải đường phẳng.
• Theo dõi tỷ lệ lỗi theo phiên bản. Spike thường báo parsing hoặc validation làm hỏng client cũ.
• Sửa endpoint lỗi hàng đầu trước, rồi mở rộng rollout.
• Chỉ retire khi active usage thực sự thấp, và thông báo ngày.
• Xóa code fallback sau cùng, sau cửa sổ retirement.

Viết chính sách versioning và deprecation trên một trang, rồi biến checklist thành release gate mà team tuân theo mỗi lần.

Nếu bạn đang xây internal tool hoặc app khách hàng trên nền tảng no-code, vẫn hữu ích khi coi API như hợp đồng có cửa sổ deprecation rõ ràng. Với đội dùng AppMaster (appmaster.io), giữ v1 và v2 song song thường dễ hơn vì bạn có thể tái tạo backend và client khi yêu cầu thay đổi trong khi vẫn giữ các hợp đồng cũ chạy trong rollout.