Khi một web/app phát triển, API hiếm khi đứng yên. Tên trường được đổi, quy tắc phân trang thay đổi, thêm trạng thái mới hoặc một endpoint cũ không còn phù hợp. Nếu thay đổi mà không có chiến lược, ứng dụng mobile chưa cập nhật, đối tác bên ngoài và các dịch vụ nội bộ có thể đồng loạt lỗi. Tương thích ngược vì thế không chỉ là vấn đề kỹ thuật, mà còn là cách giảm rủi ro khi phát hành. 1. Phân biệt thay đổi an toàn và thay đổi phá vỡ Một số thay đổi thường an toàn nếu client được thiết kế đúng: - Thêm trường mới vào response. - Thêm một endpoint mới. - Cho phép thêm giá trị tùy chọn trong request. Ngược lại, các thay đổi sau có thể phá vỡ client cũ: - Đổi tên hoặc xóa trường đang được sử dụng. - Đổi kiểu dữ liệu, chẳng hạn từ số sang chuỗi. - Thay đổi ý nghĩa của mã trạng thái HTTP. - Biến một trường tùy chọn thành bắt buộc. - Trả về một cấu trúc hoàn toàn khác trong cùng endpoint. Không nên giả định rằng “thêm trường” luôn an toàn. Một số client viết bộ phân tích dữ liệu quá chặt, chỉ chấp nhận đúng tập trường đã biết. Vì vậy, cần kiểm thử với các client quan trọng trước khi triển khai. 2. Ưu tiên thay đổi mang tính cộng thêm Khi cần mở rộng API, hãy giữ nguyên hợp đồng cũ và bổ sung khả năng mới. Ví dụ, thay vì đổi trường name thành display_name, có thể trả về cả hai trong giai đoạn chuyển tiếp. Server tiếp tục duy trì name, còn client mới bắt đầu sử dụng display_name. Sau khi xác định toàn bộ client đã chuyển đổi, mới xem xét loại bỏ trường cũ theo một lịch trình rõ ràng. Với request, nên thêm trường tùy chọn trước, đặt giá trị mặc định hợp lý ở phía server và chỉ chuyển thành bắt buộc khi có phiên bản API hoặc kế hoạch di chuyển phù hợp. Cách này đặc biệt hữu ích với ứng dụng mobile, vì người dùng có thể chưa cập nhật phiên bản mới trong nhiều tuần. 3. Thiết kế lỗi ổn định và dễ xử lý Response lỗi cũng là một phần của hợp đồng API. Nên thống nhất cấu trúc gồm mã lỗi ổn định, thông điệp dành cho lập trình viên và thông tin chi tiết nếu cần. Client nên dựa vào mã lỗi, không nên phân tích chuỗi thông báo tiếng Việt hoặc tiếng Anh. Ví dụ, thay vì chỉ trả về “Dữ liệu không hợp lệ”, server có thể cung cấp mã INVALID_INPUT và danh sách trường sai. Thông điệp có thể thay đổi theo ngôn ngữ, nhưng mã lỗi vẫn giữ nguyên để client quyết định cách hiển thị hoặc thử lại. 4. Dùng kiểm thử hợp đồng Kiểm thử đơn vị và kiểm thử tích hợp chưa chắc phát hiện được việc server vô tình đổi response. Kiểm thử hợp đồng giúp kiểm tra những điều client thực sự kỳ vọng: trường nào luôn có, kiểu dữ liệu là gì, mã trạng thái nào được trả về và quy tắc xác thực ra sao. Trong quy trình CI/CD, có thể chạy bộ kiểm thử này trước khi cho phép merge hoặc triển khai. Các client quan trọng nên cung cấp những trường hợp sử dụng thực tế, chẳng hạn đăng nhập, tạo đơn hàng và lấy danh sách có phân trang. 5. Có kế hoạch ngừng hỗ trợ Đừng xóa endpoint cũ ngay khi endpoint mới sẵn sàng. Hãy ghi rõ thời điểm ngừng hỗ trợ, cập nhật tài liệu, thông báo cho nhóm sử dụng API và theo dõi log để biết client nào vẫn còn gọi phiên bản cũ. Nếu có thể, bổ sung cảnh báo trong response hoặc dashboard nội bộ, nhưng không nên làm thay đổi định dạng khiến client cũ bị lỗi. Một quy trình thực tế có thể là: ghi nhận nhu cầu thay đổi, phân loại mức độ phá vỡ, thiết kế phương án tương thích, thêm kiểm thử hợp đồng, triển khai song song, theo dõi mức sử dụng rồi mới loại bỏ phần cũ. API được thiết kế để tiến hóa sẽ giúp đội phát triển phát hành thường xuyên hơn mà không biến mỗi lần cập nhật thành một cuộc di chuyển khẩn cấp.