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

API มีเวอร์ชันเมเจอร์เดียวคือ /v1 และมีแต่จะเพิ่มขึ้น ระบบที่เชื่อมต่อซึ่งเขียนขึ้นวันนี้จะยังทำงานได้เมื่อมีฟีเจอร์ใหม่เข้ามา สิ่งที่ระบบนั้นพึ่งพาจะไม่ถูกเปลี่ยนชื่อ ไม่ถูกนำออก และไม่ได้รับความหมายใหม่

หมายเลขเวอร์ชัน

API มีหมายเลขเวอร์ชัน เช่น 1.62.0 ซึ่งเปลี่ยนทุกครั้งที่มีการเผยแพร่:

เลข ไมเนอร์ เปลี่ยนเมื่อมีสิ่งใหม่เพิ่มเข้ามา เช่น เอนด์พอยต์ ฟิลด์ หรืออีเวนต์
เลข แพตช์ เปลี่ยนเมื่อมีการแก้คำอธิบายหรือข้อความแจ้ง โดยไม่มีสิ่งอื่นเปลี่ยนแปลง

คุณดูเวอร์ชันที่ที่อยู่หนึ่งให้บริการอยู่ได้ทุกเมื่อ:

ที่ใด	อะไร
`GET /openapi.json`	`info.version` ของข้อกำหนด
ทุกอีเวนต์ของ ฟีดอีเวนต์ และทุกเว็บฮุก	`api_version` คือเวอร์ชันที่ `data` ใช้สคีมาตาม

GET /v1/health ก็มี version เช่นกัน แต่เป็นเวอร์ชันของรุ่นเผยแพร่ Sursa ที่ให้บริการที่อยู่นั้น ไม่ใช่เวอร์ชันของ API

คุณไม่ต้องเลือกเวอร์ชันไมเนอร์ เพราะทุกคำขอได้รับบริการจากเวอร์ชันปัจจุบัน และด้วยกฎด้านล่าง การทำเช่นนี้จึงปลอดภัย

สิ่งที่เปลี่ยนแปลงได้ใน /v1

การเปลี่ยนแปลงต่อไปนี้มาได้ในทุกเวอร์ชันไมเนอร์ ให้เขียนระบบที่เชื่อมต่อให้รองรับได้โดยไม่เสียหาย:

เอนด์พอยต์ใหม่
พารามิเตอร์และฟิลด์ของคำขอใหม่ที่ ไม่บังคับ คำขอที่ไม่มีสิ่งเหล่านี้ทำงานเหมือนเดิม
ฟิลด์ใหม่ในการตอบกลับ ออบเจ็กต์ และอีเวนต์
ค่าใหม่ของ enum ในการตอบกลับ เช่น สถานะการ์ดใหม่หรือประเภทอีเวนต์ใหม่
รหัสข้อผิดพลาดใหม่และเฮดเดอร์การตอบกลับใหม่
ขีดจำกัดที่เข้มงวดน้อยลง เช่น ความยาวสูงสุดที่ยาวขึ้น หรือช่วงค่าที่กว้างขึ้น
ข้อความ message ของข้อผิดพลาดและคำอธิบายที่เรียบเรียงใหม่

สิ่งที่โค้ดของคุณต้องรองรับ

ละเว้นฟิลด์ที่ไม่รู้จัก อย่าล้มเหลวเมื่อการตอบกลับมีฟิลด์มากกว่าที่คาด และอย่าใช้สคีมาแบบเข้มงวดที่ปฏิเสธฟิลด์เหล่านั้น
ยอมรับค่า enum ที่ไม่รู้จัก enum ทุกชุดในการตอบกลับมีค่าเพิ่มได้ ให้ถือว่าค่าที่ไม่รู้จักเป็น “ค่าอื่น” ไม่ใช่ข้อผิดพลาด
ข้ามประเภทอีเวนต์ที่ไม่รู้จัก ทั้งในเว็บฮุกและในสตรีม
จัดการรหัสข้อผิดพลาดที่ไม่รู้จักตามสถานะ HTTP ดู ข้อผิดพลาด
อย่าพึ่งพาลำดับของฟิลด์ ในออบเจ็กต์ JSON หรือถ้อยคำที่แน่นอนของข้อความ

สิ่งที่ไม่เปลี่ยนเลยใน /v1

พาธ พารามิเตอร์ ฟิลด์ หรือค่า enum จะไม่ถูกเปลี่ยนชื่อหรือนำออก
ชนิดของฟิลด์ไม่เปลี่ยน และฟิลด์จะไม่ได้รับความหมายใหม่ เช่น หน่วยใหม่
คำขอที่ระบบยอมรับวันนี้จะไม่ถูกปฏิเสธในภายหลัง
รหัสสถานะของการตอบกลับเมื่อสำเร็จยังคงเดิม
รหัสข้อผิดพลาดคงความหมายเดิม และฟิลด์ detail ของการตอบกลับที่เป็นข้อผิดพลาดคงรูปแบบเดิม
ประเภทอีเวนต์จะไม่ถูกเปลี่ยนชื่อหรือนำออก และ data ของอีเวนต์มีแต่จะได้ฟิลด์เพิ่ม

การเปลี่ยนแปลงที่ไม่เข้ากันกับของเดิม

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

เมื่อเส้นทางใดกำลังจะยุติการให้บริการ:

เส้นทางนั้นจะมีเครื่องหมาย deprecated ในข้อกำหนด และระบุไว้ในบันทึกการเปลี่ยนแปลงพร้อมวันที่จะปิดใช้งาน
การตอบกลับของเส้นทางนั้นมีเฮดเดอร์ Deprecation: true และ Sunset: <date>
เส้นทางนั้นยังทำงานต่ออย่างน้อย 180 วัน หลังการประกาศ องค์กรที่คีย์ API ใช้เส้นทางนั้นจะได้รับแจ้งเป็นลายลักษณ์อักษรล่วงหน้าอย่างน้อย 90 วัน
หลังวันยุติการให้บริการ เส้นทางนั้นจะตอบกลับ 410 พร้อมรหัส api.gone ต่อไปอีก 90 วัน

คอยดูเฮดเดอร์ Deprecation ในล็อกหรือระบบเฝ้าระวังของคุณ เพราะเป็นสัญญาณแรกสุดว่าเส้นทางที่คุณใช้กำลังจะหายไป

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

บันทึกการเปลี่ยนแปลงของพอร์ทัลนี้แสดงทุกการเผยแพร่พร้อมสิ่งที่เพิ่มเข้ามาและสิ่งที่เลิกใช้แล้ว ก่อนอัปเกรดระบบที่เชื่อมต่อของคุณ ให้เทียบโค้ดกับรายการตั้งแต่เวอร์ชันที่คุณใช้พัฒนาระบบนั้น