นโยบายการเลิกใช้งาน

นโยบายการเลิกใช้งาน

หน้านี้อธิบายสิ่งที่เรารับปากเมื่อมีการเปลี่ยนแปลงบางอย่างใน public API และสิ่งที่คุณพึ่งพาได้ว่าจะยังคงเสถียร

อะไรถือเป็นการเปลี่ยนแปลงที่ทำลายความเข้ากันได้

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

• การลบ endpoint, ฟิลด์ หรือประเภทเหตุการณ์ webhook
• การเปลี่ยนชื่อฟิลด์ หรือเปลี่ยนชนิด/ความหมายของฟิลด์
• การทำให้ฟิลด์คำขอที่เคยไม่บังคับกลายเป็นบังคับ
• การเพิ่มความเข้มงวดของการตรวจสอบข้อมูลในฟิลด์ที่มีอยู่แล้ว จนทำให้คำขอที่เคยได้รับการยอมรับเริ่มถูกปฏิเสธ
• การเปลี่ยนความหมายของ status code ที่มีอยู่แล้วสำหรับสถานการณ์เดิม

สิ่งต่อไปนี้ ไม่ ถือเป็นการเปลี่ยนแปลงที่ทำลายความเข้ากันได้ และสามารถปล่อยออกได้ตลอดเวลาโดยไม่ต้องแจ้งล่วงหน้า:

• การเพิ่ม endpoint, ฟิลด์, ประเภทเหตุการณ์ webhook หรือ scope ใหม่
• การเพิ่มพารามิเตอร์คำขอใหม่ที่ไม่บังคับ
• การเพิ่มฟิลด์ใหม่ใน response body หรือ webhook payload — เขียนระบบของคุณให้เพิกเฉยต่อฟิลด์ที่ไม่รู้จักเสมอ
• การเพิ่มค่า enum ใหม่ในฟิลด์ที่คุณไม่ได้ใช้ switch ครอบคลุมทุกกรณีโดยไม่มี default (ดูข้อสังเกตด้านล่าง)

จัดการค่าที่ไม่รู้จักอย่างนุ่มนวล

เขียนระบบของคุณให้ทนทานต่อฟิลด์ใหม่ใน JSON object และค่าใหม่ในฟิลด์ที่ดูเหมือนจะมีตัวเลือกคงที่ (เช่น status หรือ event type) ให้ถือว่าค่าที่ไม่รู้จักคือ “บันทึกแล้วข้ามไป” ไม่ใช่ “ล่ม” — นี่คือสิ่งที่ทำให้การเปลี่ยนแปลงแบบเพิ่มเติมไม่ทำลายความเข้ากันได้ สำหรับคุณ ไม่ใช่แค่สำหรับเรา

วิธีที่เราประกาศการเลิกใช้งาน

เมื่อเราจำเป็นต้องทำการเปลี่ยนแปลงที่ทำลายความเข้ากันได้จริงๆ เราจะเลิกใช้งานพฤติกรรมเดิมก่อนที่จะลบออก:

1. เราประกาศการเลิกใช้งาน เหตุผล เส้นทางการย้ายระบบ และวันปิดใช้งาน
2. ทุกการตอบกลับจาก route หรือฟิลด์ที่เลิกใช้จะถูกทำเครื่องหมายด้วย header Deprecation และ Sunset — ดูรูปแบบ header ที่ชัดเจนได้ที่ การกำหนดเวอร์ชัน
3. พฤติกรรมที่เลิกใช้จะยังทำงานต่อไปโดยไม่เปลี่ยนแปลง จนถึงวันที่ Sunset ที่ประกาศไว้
4. หลังจากวันที่ Sunset route ที่เลิกใช้จะตอบกลับ 404 (หรือฟิลด์ที่เลิกใช้จะถูกลบออกจากการตอบกลับจริงๆ)

เราจะไม่ประกาศเลิกใช้งานแล้วลบออกในประกาศเดียวกัน — จะมีระยะเวลาผ่อนผันเสมอ และความยาวของระยะเวลานั้นจะระบุไว้ในประกาศเอง (ขึ้นอยู่กับว่าการเปลี่ยนแปลงนั้นส่งผลกระทบต่อผู้เชื่อมต่อระบบมากน้อยเพียงใด)

ประเภทเหตุการณ์ Webhook

นโยบายเดียวกันนี้ใช้กับประเภทเหตุการณ์ webhook ด้วย: ประเภทเหตุการณ์จะไม่มีวันถูกเปลี่ยนความหมายไปเป็นอย่างอื่น หากประเภทเหตุการณ์ใดจำเป็นต้องถูกแทนที่ ประเภทเดิมจะถูกเลิกใช้ (ยังคงส่งอยู่ ตามตารางเวลาเดียวกับด้านบน) ในขณะที่ประเภทใหม่ถูกนำมาใช้ และ endpoint ของคุณจะยังได้รับประเภทที่สมัครรับไว้ต่อไปตลอดระยะเวลาการเลิกใช้งาน

เวอร์ชัน

v1 เป็นเวอร์ชันเดียวในปัจจุบัน หากในอนาคตเราจำเป็นต้องปล่อย v2 ออกมา v1 จะไม่หยุดทำงานทันทีที่ v2 เปิดตัว — จะเป็นไปตามกระบวนการเลิกใช้งานเดียวกันนี้ ตามตารางเวลาของตัวเอง แยกจาก v2 โดยสิ้นเชิง

ติดตามข่าวสาร

• ติดตาม header Deprecation/Sunset ในบันทึก/การเฝ้าระวังของคุณเอง — นี่คือสัญญาณที่เชื่อถือได้มากที่สุด เพราะมาจาก route ที่คุณเรียกใช้จริง
• ประกาศการเลิกใช้งานจะถูกเผยแพร่ผ่านช่องทางบัญชีปกติของคุณด้วย (release notes / การแจ้งเตือนในแดชบอร์ด)