API Migration Guide — อัปเกรดระหว่างเวอร์ชัน

ภาพรวมการย้ายเวอร์ชัน

Smart Money API ถูกพัฒนาอย่างต่อเนื่องด้วยการอัปเดตเป็นประจำ คู่มือนี้ครอบคลุมการจัดการเวอร์ชัน การเปลี่ยนแปลงที่ทำให้ไม่รองรับเวอร์ชันเก่า และวิธีการย้ายการเชื่อมต่อของคุณโดยไม่มีการหยุดทำงาน

หลักสำคัญในการย้ายเวอร์ชัน:

• การกำหนดเวอร์ชันเชิงความหมาย — รูปแบบ MAJOR.MINOR.PATCH ถูกปฏิบัติตามอย่างเคร่งครัด
• การสนับสนุนระยะยาว — เวอร์ชันหลักก่อนหน้านี้ได้รับการสนับสนุนเป็นเวลา 24+ เดือน
• คำเตือนการยกเลิกการใช้งาน — แจ้งล่วงหน้า 6 เดือนสำหรับการเปลี่ยนแปลงที่ทำให้ไม่รองรับเวอร์ชันเก่า
• การทำงานแบบคู่ขนาน — ใช้งาน v1 และ v2 พร้อมกันในช่วงการย้ายเวอร์ชัน
• การทดสอบอัตโนมัติ — มีเครื่องมือทดสอบความเข้ากันได้ให้ใช้งาน

นโยบายการกำหนดเวอร์ชัน

การกำหนดเวอร์ชันเชิงความหมาย

วงจรการเผยแพร่เวอร์ชัน

ความเข้ากันได้ย้อนหลัง

ความเข้ากันได้ของเวอร์ชัน

ภายในเวอร์ชันหลัก คุณสามารถอัปเกรดไปยังเวอร์ชันย่อย/แพตช์ใหม่ได้อย่างปลอดภัยเสมอ:

• URL ของ Endpoint — ไม่เปลี่ยนแปลง
• ฟิลด์ที่จำเป็น — ไม่เคยถูกนำออก (เพิ่มเฉพาะฟิลด์เสริมใหม่เท่านั้น)
• รหัสสถานะ HTTP — ยังคงเหมือนเดิมสำหรับสถานการณ์ที่มีอยู่
• โครงสร้างการตอบกลับ — ฟิลด์หลักยังคงเหมือนเดิม
• การตรวจสอบสิทธิ์ — ไม่มีการเปลี่ยนแปลงกลไกการตรวจสอบสิทธิ์

การยกเลิกการใช้งานอย่างราบรื่น

การย้ายจาก V1 ไป V2

การเปลี่ยนแปลงหลัก

• การออกแบบ REST API ใหม่ — Endpoint ของทรัพยากรที่สะอาดขึ้น
• รูปแบบการตอบกลับ — การห่อหุ้มที่สม่ำเสมอ, การจัดการข้อผิดพลาดที่ดีขึ้น
• การตรวจสอบสิทธิ์ — เพิ่มการสนับสนุน OAuth 2.0 (ยังใช้คีย์ API ได้)
• การจำกัดอัตรา — ความละเอียดและความชัดเจนที่ดีขึ้น
• Webhooks — รูปแบบเหตุการณ์และการเซ็นใหม่

การแมป Endpoint

การเปลี่ยนแปลงของ Endpoint

การเปลี่ยนแปลงพารามิเตอร์คำขอ

การอัปเดตรูปแบบการตอบกลับ

โครงสร้างการตอบกลับ V1

โครงสร้างการตอบกลับ V2

ความแตกต่างหลัก: ไม่มี status wrapper, ชื่อฟิลด์ชัดเจนขึ้น, มาตรฐาน metadata

ระยะเวลาการเลิกใช้งาน

แผนการเลิกใช้งาน

รายละเอียดการเปลี่ยนแปลงที่สำคัญ

จุดสิ้นสุดที่ถูกยกเลิก

• /v1/stats — ถูกแทนที่โดย /v2/metrics
• /v1/historical — ถูกแทนที่โดย /v2/historical พร้อมพารามิเตอร์ใหม่
• /v1/alerts/create — ถูกแทนที่โดย POST /v2/alerts

การเปลี่ยนแปลงพารามิเตอร์

• limit — ค่าเริ่มต้นเปลี่ยนจาก 100 เป็น 20 (ระบุให้ชัดเจน!)
• timeframe — ตอนนี้จำเป็นสำหรับการค้นหาข้อมูลย้อนหลัง
• sort — รูปแบบเปลี่ยนจาก "field asc" เป็น "field:asc"

การเปลี่ยนแปลงฟิลด์การตอบกลับ

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

การโยกย้ายแบบทีละขั้นตอน

ขั้นตอนที่ 1: การวางแผน (สัปดาห์ 1-2)

1. ตรวจสอบการเชื่อมต่อที่มีอยู่สำหรับฟีเจอร์ที่ถูกเลิกใช้
2. แมปจุดสิ้นสุด v1 กับ v2 ที่เทียบเท่า
3. ระบุการเปลี่ยนแปลงสำคัญที่ส่งผลต่อโค้ดของคุณ
4. วางแผนกลยุทธ์การทดสอบและไทม์ไลน์

ขั้นตอนที่ 2: การพัฒนา (สัปดาห์ 3-4)

1. สร้างสาขา v2 ในระบบควบคุมเวอร์ชัน
2. อัปเดตจุดสิ้นสุด API ทั้งหมดเป็น URL v2
3. อัปเดตการจัดการคำขอ/การตอบกลับ
4. รันการทดสอบหน่วยกับ sandbox

ขั้นตอนที่ 3: การทดสอบ (สัปดาห์ 5-6)

1. รันชุดการทดสอบการเชื่อมต่อเต็มรูปแบบ
2. ทดสอบสถานการณ์ผิดพลาดและกรณีขอบเขต
3. ทดสอบโหลดกับจุดสิ้นสุด v2
4. การตรวจสอบความปลอดภัยของโค้ดที่อัปเดต

ขั้นตอนที่ 4: การเตรียมพร้อม (สัปดาห์ 7)

1. ปรับใช้โค้ด v2 ในสภาพแวดล้อม staging
2. รันการทดสอบการยอมรับเต็มรูปแบบ
3. รับการอนุมัติจากผู้มีส่วนได้ส่วนเสีย
4. เตรียมแผนการย้อนกลับ

ขั้นตอนที่ 5: การผลิต (สัปดาห์ 8)

1. ปรับใช้แบบ blue-green ในสภาพแวดล้อมการผลิต
2. ตรวจสอบเมตริกและอัตราความผิดพลาด
3. เตรียมพร้อมสำหรับปัญหาการสนับสนุน
4. ยกเลิกการใช้โค้ด v1 อย่างค่อยเป็นค่อยไป

การสนับสนุนและทรัพยากร

เครื่องมือที่พร้อมใช้งาน

• Migration Validator — ตรวจสอบโค้ดสำหรับการใช้งานที่ถูกเลิกใช้
• API Upgrade Checker — เปรียบเทียบความเข้ากันได้ของ v1 และ v2
• Migration Checklist — PDF พร้อมงานและไทม์ไลน์
• ตัวอย่างโค้ด — ตัวอย่างก่อน/หลังการโยกย้าย

รับความช่วยเหลือ

• อีเมล: [email protected]
• เอกสาร: ดู changelog-versioning.html
• Discord: ช่องสนับสนุนชุมชน
• Enterprise: วิศวกรโยกย้ายเฉพาะ