การกำหนดเวอร์ชัน
Partner API กำหนดเวอร์ชันไว้ใน URL เวอร์ชันปัจจุบันคือ:
https://partner-api.performancehub.co/partner/v1/
นโยบายการเปลี่ยนแปลง
Performance Hub มุ่งทำการเปลี่ยนแปลงแบบเพิ่มเติมที่เข้ากันได้กับเวอร์ชันก่อนหน้าทุกครั้งที่ทำได้
ตัวอย่างการเปลี่ยนแปลงที่เข้ากันได้กับเวอร์ชันก่อนหน้า:
- การเพิ่มฟิลด์ใหม่แบบไม่บังคับในคำขอ
- การเพิ่มฟิลด์ใหม่ในการตอบกลับ
- การเพิ่มปลายทางใหม่
- การเพิ่มค่า enum ใหม่ในกรณีที่ไคลเอนต์ควรรองรับค่าที่ไม่รู้จัก
- การปรับปรุงข้อความการตรวจสอบความถูกต้องโดยไม่เปลี่ยนข้อตกลงของรหัสสถานะ
access_time_windows และ access_time_windows_revision เป็นฟิลด์คำขอของ Member แบบเพิ่มเติม ไคลเอนต์ที่มีอยู่ซึ่งไม่ส่งฟิลด์เหล่านี้จะคงสแนปช็อต Access Time Window ที่จัดเก็บไว้โดยไม่เปลี่ยนแปลง กฎการเว้นค่านี้รักษาความเข้ากันได้ของการ upsert บางส่วน การเว้นค่าไม่เทียบเท่ากับการส่งอาร์เรย์ว่าง
ตัวอย่างการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากัน:
- การนำฟิลด์ออกหรือเปลี่ยนชื่อฟิลด์
- การเปลี่ยนประเภทของฟิลด์
- การเปลี่ยนฟิลด์คำขอที่ไม่บังคับให้เป็นฟิลด์ที่จำเป็น
- การนำปลายทางออก
- การเปลี่ยนความหมายของรหัสสถานะที่มีอยู่หรือ
reasonเฉพาะโดเมน
การเลิกใช้งาน
เมื่อจำเป็นต้องมีการเปลี่ยนแปลงที่ทำให้เกิดความไม่เข้ากัน Performance Hub จะหลีกเลี่ยงการเปลี่ยนแปลงเวอร์ชันที่มีอยู่โดยตรงเท่าที่ทำได้ แต่จะเปิดตัวเวอร์ชันใหม่หรือแนวทางการย้ายระบบ และแจ้งการเปลี่ยนแปลงให้พาร์ทเนอร์ที่ได้รับผลกระทบทราบ
ประกาศการเลิกใช้งานอาจรวมถึง:
- รายการในบันทึกการเปลี่ยนแปลง
- การสื่อสารกับพาร์ทเนอร์โดยตรง
- หมายเหตุใน Partner Console
- คำแนะนำการย้ายระบบในเอกสาร
คำแนะนำสำหรับไคลเอนต์
สร้างไคลเอนต์ที่รองรับการเปลี่ยนแปลงแบบเพิ่มเติมได้:
- ละเว้นฟิลด์การตอบกลับที่คุณไม่ได้ใช้
- ถือว่าค่า enum ที่ไม่รู้จักเป็นค่าที่ไม่รองรับ แทนที่จะทำให้ระบบขัดข้อง
- หลีกเลี่ยงการตรวจสอบการตอบกลับว่าตรงกันทุกประการอย่างเคร่งครัด
- บันทึกค่าที่ไม่รู้จักไว้เพื่อให้คุณอัปเดตการผสานรวมได้อย่างตั้งใจ
สำหรับพาร์ทิชันของ Member ที่มีการกำหนดเวอร์ชัน เช่น Access Time Windows ให้เก็บเวอร์ชันและเพย์โหลดที่ปรับให้เป็นมาตรฐานที่ส่งไปไว้จนกว่าจะทราบผลลัพธ์ การใช้เวอร์ชันเดิมซ้ำกับเนื้อหาที่เปลี่ยนแปลงถือเป็นความขัดแย้ง ส่วนการส่งเนื้อหาเดิมซ้ำเป็นแบบ Idempotent ดู Access Time Windows
ข้อกำหนด OpenAPI
ใช้ข้อกำหนด OpenAPI ที่เผยแพร่เพื่อสร้างไคลเอนต์ ตรวจสอบความถูกต้องของคำขอ และติดตามการเปลี่ยนแปลงโครงสร้างของ API เมื่อเวลาผ่านไป