การกำหนดเวอร์ชันของ API
API สาธารณะใช้ เวอร์ชันแบบระบุวันที่ ซึ่งเป็นรูปแบบเดียวกับ Shopify เวอร์ชันที่คุณพัฒนาอยู่จึงไม่เปลี่ยนไปโดยที่คุณไม่รู้ตัว เวอร์ชันแบบระบุวันที่คือเส้นแบ่งหยาบ ๆ สำหรับการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้ ส่วนภายในเวอร์ชันเดียวกัน สคีมายังคงพัฒนาต่อไปด้วยการเพิ่มเติมเท่านั้น
ชื่อเวอร์ชัน
เวอร์ชันมีชื่อเป็น YYYY-MM โดยเดือนคือเดือนเริ่มต้นไตรมาส ได้แก่ 2026-01, 2026-04, 2026-07, 2026-10 เวอร์ชันแบบระบุวันที่ใหม่จะออก เฉพาะเมื่อมีการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้ เท่านั้น ไตรมาสที่ไม่มีการเปลี่ยนแปลงลักษณะนี้จะถูกข้ามไป เวอร์ชันจึงมีไม่บ่อยนัก
นอกจากนี้ยังมีเวอร์ชัน unstable ที่ตามความคืบหน้าล่าสุดของการพัฒนา ไว้ดูตัวอย่างการเปลี่ยนแปลงก่อนออกเวอร์ชันเสถียร อย่าสร้างการเชื่อมต่อสำหรับใช้งานจริงบนเวอร์ชันนี้
การเลือกเวอร์ชัน
มีสองวิธี เรียงตามลำดับความสำคัญ:
- ระบุในพาธของ URL (แนะนำ): ใส่เวอร์ชันไว้ในเอนด์พอยต์ —
…/backend/<subdomain>/api/2026-07/graphqlวิธีนี้ชัดเจน เป็นมิตรกับแคช และคัดลอกไปใช้ได้ทันที - ระบุในส่วนหัวของคำขอ: ส่ง
X-Api-Version: 2026-07ไปยังเอนด์พอยต์เปล่า…/backend/<subdomain>/graphql
หากคุณไม่ระบุเวอร์ชัน — หรือระบุเวอร์ชันที่ไม่รู้จักหรือเลยกำหนดสิ้นสุดการสนับสนุนไปแล้ว — คำขอจะถูกให้บริการโดย เวอร์ชันเก่าที่สุดที่ยังได้รับการสนับสนุน ไม่ใช่เวอร์ชันใหม่ที่สุด คุณจะไม่ถูกย้ายไปยังการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้อย่างเงียบ ๆ สำหรับการเชื่อมต่อที่คุณตั้งใจดูแลระยะยาว ให้ตรึงเวอร์ชันไว้อย่างชัดเจน
ทุกการตอบกลับจะระบุเวอร์ชันที่ให้บริการคำขอนั้น ไว้ในส่วนหัว X-Api-Version คุณจึงรู้เสมอว่าข้อตกลงชุดใดเป็นผู้ตอบ และตรวจพบความคลาดเคลื่อนได้หากคุณเคยพึ่งพาพฤติกรรมเริ่มต้น
ระยะเวลาสนับสนุน
เวอร์ชันเสถียรแต่ละเวอร์ชันได้รับการสนับสนุน อย่างน้อย 12 เดือน และ ทับซ้อนกับเวอร์ชันถัดไปอย่างน้อย 9 เดือน ในทางปฏิบัติจะมีสองถึงสามเวอร์ชันใช้งานอยู่พร้อมกัน ซึ่งเป็นช่วงเวลาที่เพียงพอสำหรับการย้ายระบบ วันสิ้นสุดการสนับสนุนของแต่ละเวอร์ชันจะประกาศในวันที่เวอร์ชันนั้นออก
อะไรนับเป็นการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้
ภายในเวอร์ชันเดียวกัน เราอาจทำการเปลี่ยนแปลง แบบเพิ่มเติม และไคลเอนต์ของคุณต้องรองรับได้:
- เพิ่มไทป์ คิวรี หรือมิวเทชันใหม่
- เพิ่มอาร์กิวเมนต์ ที่ไม่บังคับ ให้ฟิลด์ที่มีอยู่
- เพิ่มฟิลด์ให้ออบเจ็กต์ไทป์
- เพิ่มค่าให้ enum (ดังนั้นอย่าสันนิษฐานว่า enum เป็นชุดปิด)
เวอร์ชันแบบระบุวันที่ใหม่ สงวนไว้สำหรับการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้จริง ๆ เช่น การลบหรือเปลี่ยนชื่อฟิลด์หรือไทป์ การบังคับเงื่อนไขค่าว่างให้เข้มขึ้น หรือการเปลี่ยนความหมายของอาร์กิวเมนต์หรือค่าเริ่มต้น สิ่งเหล่านี้จะไม่เกิดขึ้นภายในเวอร์ชันเดิม — เวอร์ชันที่คุณตรึงไว้จะคงพฤติกรรมเดิมจนถึงวันสิ้นสุดการสนับสนุน
การเลิกใช้งาน
การเลิกใช้งานจะแจ้งผ่านสองช่องทาง เพื่อให้คุณรู้ก่อนที่อะไรจะพัง:
- ในสคีมา ฟิลด์ที่กำลังจะเลิกใช้จะถูกกำกับด้วย
@deprecatedพร้อมเหตุผลที่ระบุตัวแทน การทำ introspection และ GraphQL Playground จะแสดงข้อมูลนี้ให้ทุกไคลเอนต์โดยอัตโนมัติ - ในการตอบกลับ เมื่อคำขอเรียกใช้ฟิลด์ที่เลิกใช้งานจริง ๆ การตอบกลับจะมีส่วนหัว
X-Api-Deprecated-Reason(และรายการextensions.deprecationsที่สอดคล้องกัน) ระบุรายการเลิกใช้งานที่คำขอนั้นแตะต้อง การเลิกใช้งานจึงปรากฏในบันทึกของคุณทันทีที่คุณไปเจอ โดยไม่ต้องตามหาเอง
ฟิลด์ที่เลิกใช้งานจะยังคงอยู่ตามระยะเวลาขั้นต่ำที่ประกาศไว้ ก่อนจะถูกลบออกในเวอร์ชันแบบระบุวันที่ถัดไป