Chuyển phiên bản

TL;DR — Key của bạn được ghim vào một phiên bản theo ngày. Khi Wandura phát hành phiên bản mới hơn: đọc những gì đã thay đổi, thử nó theo từng request bằng header Wandura-Version, rồi chuyển key (key mới được ghim vào phiên bản mới nhất; key được xoay vòng giữ nguyên phiên bản đã ghim). Một major version mới (/v2) có 12 tháng chạy song song.

Hiện có một phiên bản theo ngày, 2026-10-02, nên chưa có gì để chuyển. Trang này là quy trình cho lúc cần chuyển.

1. Biết mình đang ở đâu#

curl -s https://www.wandura.ai/api/delivery/v1/config \
  -H "Authorization: Bearer $WANDURA_API_KEY"

api.pinned_version là phiên bản của key bạn, api.latest_version là phiên bản mới nhất, api.supported_versions là các phiên bản bạn được gửi, mỗi phiên bản kèm deprecated_at và sunset_at. Mọi response cũng cho biết phiên bản đã dùng, trong Wandura-Version. Hãy ghi log header đó.

2. Đọc những gì đã thay đổi#

Lịch sử phiên bản, changelog, và https://docs.wandura.ai/changes.json (api_versions) liệt kê từng phiên bản và các thay đổi của nó.

3. Thử phiên bản mới theo từng request#

Gửi Wandura-Version: <ngày mới> trên vài request từ một môi trường test (tốt nhất là tổ chức test của bạn). Header này ghi đè phiên bản đã ghim của key chỉ cho request đó. Giá trị lạ hoặc đã khai tử trả 400 unsupported_version kèm các phiên bản bạn dùng được.

4. Chuyển key#

Trước khi đổi key trong tình huống khẩn cấp (key bị lộ), kiểm tra phiên bản của key mới khớp với điều code của bạn mong đợi: key mới ở phiên bản mới nhất.

5. Theo dõi deprecation#

Một phiên bản hoặc endpoint đã deprecated trả các header Deprecation, Sunset và Link trên mọi response. Hãy cảnh báo khi thấy chúng (Quan sát hệ thống). Thời gian báo trước: 30 ngày trong giai đoạn beta, 12 tháng sau đó.

Liên quan#

• Versioning và API tiến hoá