Phiên bản và ngừng hỗ trợ

TL;DR — Phiên bản nằm trong path (/v1). Thay đổi bổ sung được phát hành không báo trước. Thay đổi phá vỡ tương thích được phát hành ở phiên bản mới, và phiên bản cũ vẫn chạy 12 tháng kể từ khi công bố phiên bản mới. Trong giai đoạn beta, thay đổi phá vỡ tương thích bên trong /v1 được báo trước ít nhất 30 ngày, trừ bản vá bảo mật khẩn.

Phiên bản hoạt động thế nào#

Phiên bản API là một phần của mọi path: https://www.wandura.ai/api/delivery/v1/…. Bạn chọn phiên bản qua path bạn gọi; không có header nào cần đặt. Trong giai đoạn beta, mọi response từ /v1 còn mang Wandura-API-Status: beta.

Thay đổi không phá vỡ tương thích#

Những thay đổi này có thể xuất hiện trong phiên bản hiện tại bất cứ lúc nào, không báo trước. Hãy viết tích hợp sao cho vẫn chạy khi chúng xuất hiện:

• Thêm endpoint mới.
• Thêm tham số request tuỳ chọn.
• Thêm trường mới trong response. Bỏ qua các trường bạn không nhận ra.
• Thêm mã lỗi mới, hoặc giá trị mới trong một trường liệt kê trạng thái. Luôn có nhánh mặc định.
• Nâng rate limit.

Thay đổi phá vỡ tương thích#

Những thay đổi này không bao giờ diễn ra âm thầm. Chúng được phát hành ở phiên bản mới, hoặc trong giai đoạn beta thì theo quy tắc beta:

• Xoá hoặc đổi tên endpoint, tham số request hay trường response.
• Thêm tham số request bắt buộc.
• Đổi kiểu dữ liệu hoặc ý nghĩa của một trường đang có.
• Đổi cách xác thực, hoặc scope mà một endpoint cần.
• Trả mã lỗi khác cho một trường hợp vốn đã có mã lỗi.
• Hạ rate limit.

Thời gian hỗ trợ#

Khi một phiên bản mới (ví dụ /v2) được phát hành:

1. Wandura công bố trong nhật ký thay đổi và gửi email cho Admin của mọi tổ chức đang dùng API.
2. Phiên bản trước vẫn chạy, không đổi, trong 12 tháng kể từ lúc công bố.
3. Trong 12 tháng đó, tài liệu của phiên bản trước vẫn đọc được, có đánh dấu là phiên bản cũ, ở địa chỉ riêng (ví dụ /vi/v1/developers/…). Dùng menu phiên bản ở đầu các trang API.
4. Hết 12 tháng, phiên bản trước ngừng hoạt động. Lời gọi tới nó trả về lỗi nêu tên phiên bản cần chuyển sang.

Trong giai đoạn beta#

Khi API còn ở bản beta, Wandura vẫn có thể phải thay đổi phá vỡ tương thích bên trong /v1. Khi đó:

• Thay đổi được báo trước ít nhất 30 ngày trước khi có hiệu lực, trong nhật ký thay đổi và qua email cho Admin của mọi tổ chức đang dùng API.
• Bản vá bảo mật khẩn có thể có hiệu lực ngay. Nó được thông báo ngay khi đã chạy.

Theo dõi thay đổi ở đâu#

• Nhật ký thay đổi — link ở cuối mọi trang. Liệt kê mọi trang đã sửa, theo từng ngày.
• Lịch sử thay đổi — mỗi trang ghi lần cập nhật gần nhất và link tới lịch sử riêng, có đúng các dòng đã thêm và bớt.
• Góp ý — bấm Gửi góp ý ở đầu mọi trang nếu có chỗ chưa rõ hoặc một thay đổi làm bạn bất ngờ.