Vì các service triển khai độc lập, bạn không bao giờ có thể giả định bên gọi nâng cấp đồng loạt. API versioning cộng với tương thích ngược cho phép producer tiến hóa mà không phá vỡ các consumer hiện có.
Vì các service triển khai độc lập, bạn không bao giờ có thể giả định bên gọi nâng cấp đồng loạt. API versioning cộng với tương thích ngược cho phép producer tiến hóa mà không phá vỡ các consumer hiện có.
| Chiến lược | Ví dụ |
|---|
| Đường dẫn URI | GET /v2/orders/42 |
| Header | Accept: application/vnd.api.v2+json |
| Tiến hóa schema | thêm trường, không bao giờ xóa/đổi tên |
KHÔNG PHÁ VỠ (an toàn):
✓ thêm một trường tùy chọn mới
✓ thêm một endpoint mới
✓ thêm một giá trị enum mới (nếu client chịu được giá trị lạ)
PHÁ VỠ (cần một version mới):
✗ xóa hoặc đổi tên một trường
✗ đổi kiểu hoặc làm một trường thành bắt buộc
✗ đổi ngữ nghĩa của một trường hiện có
message Order {
string id = 1;
double total = 2;
string currency = 3; // trường 3 MỚI — client cũ bỏ qua an toàn
}
Số thứ tự trường, không phải tên, định nghĩa định dạng trên đường truyền (wire format), nên việc thêm trường là tương thích ngược.
Phát hành v2 ─▶ chạy v1 + v2 cùng nhau ─▶ di dời consumer ─▶ khai tử v1 ─▶ gỡ v1
Đừng bao giờ gỡ một version khi vẫn còn lưu lượng thật dùng nó. Hãy theo dõi mức sử dụng trước khi cho nghỉ hưu.
Khả năng triển khai độc lập chỉ hiệu quả nếu một producer có thể ship một thay đổi mà không cần phối hợp đợt release của mọi consumer.
Thiết kế cho thay đổi cộng thêm và hỗ trợ các version cũ trong lúc di dời là điều bảo toàn sự độc lập đó thay vì buộc các đợt nâng cấp big-bang mong manh.