Hướng dẫn Di chuyển API — Nâng cấp giữa các Phiên bản

Tổng quan Di chuyển

Smart Money API được phát triển tích cực với các bản cập nhật thường xuyên. Hướng dẫn này bao gồm quản lý phiên bản, các thay đổi phá vỡ và cách di chuyển tích hợp của bạn mà không có thời gian chết.

Nguyên tắc chính khi di chuyển:

• Phiên bản Ngữ nghĩa — Định dạng MAJOR.MINOR.PATCH được tuân thủ nghiêm ngặt
• Hỗ trợ Dài hạn — Phiên bản chính trước được hỗ trợ trong 24+ tháng
• Cảnh báo Ngừng hỗ trợ — Thông báo trước 6 tháng cho tất cả các thay đổi phá vỡ
• Phiên bản Song song — Chạy đồng thời v1 và v2 trong quá trình di chuyển
• Kiểm tra Tự động — Cung cấp công cụ kiểm tra tương thích

Chính sách Phiên bản

Phiên bản Ngữ nghĩa

Chu kỳ Phát hành Phiên bản

Tương thích Ngược

Tương thích Phiên bản

Trong một phiên bản chính, bạn luôn có thể nâng cấp lên các phiên bản phụ/bản vá mới hơn một cách an toàn:

• URL Điểm cuối — Không thay đổi
• Trường Bắt buộc — Không bao giờ bị xóa (chỉ thêm trường tùy chọn mới)
• Mã Trạng thái HTTP — Được giữ nguyên cho các kịch bản hiện có
• Cấu trúc Phản hồi — Các trường cốt lõi giữ nguyên
• Xác thực — Không có thay đổi về cơ chế xác thực

Ngừng hỗ trợ Nhẹ nhàng

Di chuyển từ V1 lên V2

Thay đổi Lớn

• Thiết kế lại REST API — Điểm cuối tài nguyên sạch hơn
• Định dạng Phản hồi — Bao bọc nhất quán, xử lý lỗi tốt hơn
• Xác thực — Thêm hỗ trợ OAuth 2.0 (khóa API vẫn hoạt động)
• Giới hạn Tốc độ — Cải thiện độ chi tiết và rõ ràng
• Webhooks — Định dạng sự kiện và ký được thiết kế lại

Ánh xạ Điểm cuối

Thay đổi Điểm cuối

Thay đổi Tham số Yêu cầu

Cập nhật Định dạng Phản hồi

Cấu trúc phản hồi V1

Cấu trúc phản hồi V2

Khác biệt chính: Không có lớp bọc trạng thái, tên trường rõ ràng hơn, metadata chuẩn hóa.

Lộ trình ngừng hỗ trợ

Các tính năng sẽ ngừng hỗ trợ

Chi tiết thay đổi lớn

Các endpoint đã bị loại bỏ

• /v1/stats — Được thay thế bằng /v2/metrics
• /v1/historical — Được thay thế bằng /v2/historical với tham số mới
• /v1/alerts/create — Được thay thế bằng POST /v2/alerts

Thay đổi tham số

• limit — Mặc định thay đổi từ 100 xuống 20 (cần chỉ định rõ!)
• timeframe — Giờ là bắt buộc với truy vấn lịch sử
• sort — Định dạng thay đổi từ "field asc" thành "field:asc"

Thay đổi trường phản hồi

• funding → funding_rate
• price → mark_price
• vol → volume_quote

Di chuyển từng bước

Giai đoạn 1: Lập kế hoạch (Tuần 1-2)

1. Kiểm tra tích hợp hiện tại cho các tính năng đã lỗi thời
2. Ánh xạ endpoint v1 sang v2 tương đương
3. Xác định các thay đổi lớn ảnh hưởng đến code
4. Lập chiến lược và timeline kiểm thử

Giai đoạn 2: Phát triển (Tuần 3-4)

1. Tạo branch v2 trong hệ thống quản lý phiên bản
2. Cập nhật tất cả endpoint API sang URL v2
3. Cập nhật xử lý request/response
4. Chạy unit test trên môi trường sandbox

Giai đoạn 3: Kiểm thử (Tuần 5-6)

1. Chạy toàn bộ bộ kiểm thử tích hợp
2. Kiểm tra các tình huống lỗi và edge cases
3. Kiểm tra tải với endpoint v2
4. Kiểm tra bảo mật code đã cập nhật

Giai đoạn 4: Staging (Tuần 7)

1. Triển khai code v2 lên môi trường staging
2. Chạy toàn bộ kiểm thử chấp nhận
3. Xin phê duyệt từ các bên liên quan
4. Chuẩn bị kế hoạch rollback

Giai đoạn 5: Production (Tuần 8)

1. Triển khai blue-green lên production
2. Giám sát metrics và tỷ lệ lỗi
3. Sẵn sàng hỗ trợ khi có sự cố
4. Từng bước ngừng sử dụng code v1

Hỗ trợ & Tài nguyên

Công cụ có sẵn

• Trình kiểm tra di chuyển — Kiểm tra code có sử dụng tính năng lỗi thời
• Trình kiểm tra nâng cấp API — So sánh tương thích giữa v1 và v2
• Danh sách kiểm tra di chuyển — PDF với các task và timeline
• Ví dụ code — Mẫu trước/sau khi di chuyển

Nhận trợ giúp

• Email: [email protected]
• Tài liệu: Xem changelog-versioning.html
• Discord: Kênh hỗ trợ cộng đồng
• Doanh nghiệp: Kỹ sư di chuyển chuyên trách