Thông báo một API bị deprecated không có nghĩa nó đã ngừng hoạt động. Việc cần làm là tìm ứng dụng nào còn phụ thuộc và chứng minh phiên bản thay thế xử lý đúng nghiệp vụ trước thời hạn được nhà cung cấp xác nhận.
Phân biệt cảnh báo với ngày ngừng phục vụ
Đọc thông báo và tài liệu đúng phiên bản; giữ ngày quan sát cùng nguồn. Deprecation báo hướng ngừng khuyến nghị, còn lịch ngừng phục vụ cần bằng chứng riêng. Không tự suy ra deadline từ ngày bài blog của nhà cung cấp được đăng hoặc từ một header mà ứng dụng chưa ghi nhận.
Bản đồ consumer phải có job ít chạy
Liệt kê backend, ứng dụng di động, báo cáo định kỳ và tác vụ cuối tháng. Ghi owner, credential scope, endpoint và đầu ra nghiệp vụ. Một ứng dụng không có request hôm nay vẫn có thể là phụ thuộc quan trọng nếu chỉ chạy vào ngày đối soát.
Ví dụ giả định: báo cáo cuối tháng gọi phiên bản cũ
Một công ty giả định chuyển giao diện tra cứu sang API mới nhưng quên job xuất báo cáo. Canary trên giao diện không phát hiện được sai khác bộ lọc của job. Nhóm cần chạy mẫu đối chiếu có cùng phạm vi dữ liệu và kiểm tra đầu ra báo cáo riêng, không kết luận từ việc endpoint mới trả 200.
| Consumer | Bằng chứng cần có | Điều kiện đóng |
|---|---|---|
| Giao diện thường dùng | Mẫu đầu ra và lỗi | Canary đạt |
| Job định kỳ | Một chu kỳ được kiểm tra | Owner ký nhận |
| Tích hợp ngoài | Phiên bản và quyền | Không còn lời gọi cũ |
So sánh hành vi, không chỉ tên trường
Kiểm tra phân trang, sắp xếp, quyền, cách biểu diễn giá trị trống, múi giờ và mã lỗi. Những trường không còn được trả có thể ảnh hưởng quy tắc vận hành dù chương trình vẫn chạy. Với thay đổi kiểu dữ liệu, lập hợp đồng trường riêng; bài này tập trung kế hoạch chuyển consumer và lịch release.
Canary và rollback cần điều kiện rõ
Chuyển một phạm vi nhỏ có owner, so sánh đầu ra và theo dõi lỗi theo consumer. Chốt điểm dừng trước khi mở rộng. Nếu phiên bản cũ đã bị tắt, rollback có thể không còn khả dụng; khi đó cần phương án tạm ngừng có kiểm soát hoặc đường xử lý thay thế đã duyệt.
Đóng chuyển đổi bằng bằng chứng không còn lời gọi cũ
Sau đợt chuyển, quan sát đủ chu kỳ của các job đã liệt kê. Chỉ thu hồi cấu hình cũ khi owner xác nhận và có bản ghi thay đổi. Mục tiêu là loại phụ thuộc thật, không chỉ sửa một chuỗi version trong kho mã.
Chuẩn bị gì khi trao đổi phạm vi triển khai?
Mang theo thông báo ngừng phiên bản và danh sách consumer khi cần điều chỉnh kết nối API. Phạm vi khảo sát nên gồm cả các job ít chạy, không chỉ endpoint dễ thấy trong giao diện.
Chuẩn bị tài liệu API cho consumer cần chuyển phiên bản; công cụ soạn yêu cầu không thay thế việc xác nhận hành vi trên hệ thống thực tế.
Nguồn kiểm chứng và giới hạn áp dụng
Tài liệu chính thức: RFC9745 mô tả Deprecation. Đối chiếu ngày 12/10/2026. Các bảng và quy trình trong bài là đề xuất biên tập; ví dụ giả định không phải dự án hay kết quả khách hàng Onter.
