การกำหนดเลขเวอร์ชันของ FedEx API

ที่ FedEx เราใช้หลักการมาตรฐานการตั้งหมายเลขเวอร์ชัน (ระบบ Semantic Versioning) เพื่อกำหนดเลขเวอร์ชันของ API โดยแต่ละเลขเวอร์ชันนั้นจะปรากฏในรูปแบบของ major และ minor (เช่น Ship API 1.1) ซึ่งจะเปลี่ยนเป็นเลขเวอร์ชัน major ชุดใหม่เมื่อการเปลี่ยนแปลงนั้นไม่สามารถใช้งานร่วมกับเวอร์ชันเก่าได้ และจะเปลี่ยนเป็นเลขเวอร์ชัน minor ชุดใหม่โดยที่การเปลี่ยนแปลงนั้นยังคงสามารถใช้งานร่วมกับเวอร์ชันเก่า

ที่ FedEx เรากำหนดเลขเวอร์ชันด้วย URI อย่างง่าย ซึ่งใช้ได้กับหมายเลขเวอร์ชัน major ที่แสดงในพาธ URI เท่านั้น โปรดทราบว่าหมายเลขเวอร์ชัน minor นั้นไม่ได้รวมอยู่ในพาธ URI ดังนั้น กลยุทธ์นี้จึงใช้การจัดเส้นทาง URI เพื่อระบุเวอร์ชันเฉพาะของ API

ตัวอย่างเช่น: /ship/v1/shipments

หลักกลยุทธ์ในการการกำหนดเลขเวอร์ชัน

เราวางแผนที่จะปล่อยเลขเวอร์ชัน major สำหรับ FedEx API ในจำนวนที่น้อยลง และจะเลิกใช้งานเลขเวอร์ชัน major ภายในสองปีหลังจากมีการปล่อยเลขเวอร์ชัน major ชุดใหม่กว่าออกมา เช่น มีการปล่อย major เวอร์ชัน ‘N’ โดยที่ระบบจะรองรับเวอร์ชัน ‘N-1’ เป็นระยะเวลาสองปีหลังจากปล่อยเวอร์ชัน ‘N’

ยกตัวอย่างเช่น: มีการปล่อย major เวอร์ชัน V1.0 ในปี 2020 หากในปี 2021 มีการปล่อย major เวอร์ชัน V2.0 เวอร์ชัน V1.0 ก็จะถูกยกเลิกการใช้งานในปี 2023

เลขเวอร์ชัน minor จะรองรับฟังก์ชันใหม่และการอัปเดตคุณสมบัติส่วนใหญ่

ยกตัวอย่างเช่น: จะมีการปล่อย major เวอร์ชัน 1.0 และ minor เวอร์ชัน 1.1, 1.2 รวมถึงเวอร์ชันอื่นๆ ในภายหลังเพื่อเพิ่มฟังก์ชันการทำงานและการอัปเดตคุณสมบัติใหม่ๆ

ทั้งนี้ ไม่ว่ากรณีใดก็ตาม ปลายทางทั้งหมดของแต่ละเฉพาะ API จะมีเลขเวอร์ชัน major เดียวกัน ซึ่งสามารถพบเอกสารเวอร์ชันล่าสุดได้ในFedEx Developer Portal เท่านั้น อย่างไรก็ตาม จะมีบันทึกการเปลี่ยนแปลงภายใต้หน้าภาพรวมของแต่ละ API ที่จะอธิบายรายละเอียดการเปลี่ยนแปลงของเลขเวอร์ชัน major และ minor

จะมีการปล่อยเลขเวอร์ชัน major ของ API เมื่อไหร่

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

• เมื่อมีการลบค่าการแจกแจงที่มีอยู่ หรือรูปแบบหรือค่าการแจกแจงในคำขอหรือการตอบสนองมีการเปลี่ยนแปลง
  

  ยกตัวอย่างเช่น: ค่าการแจกแจง "GEOGRAPHIC_COORDINATES" สำหรับองค์ประกอบของ locationSearchCriterion ถูกลบออกในเวอร์ชัน N หรือรูปแบบวันที่มีการเปลี่ยนแปลงจาก YY-MM-DD เป็น MM-DD-YYYY หรือมีการเปลี่ยนประเภทตำแหน่งจาก FEDEX_ONSITE เป็น ONSITE ในการตอบสนอง

• เมื่อมีการลบองค์ประกอบที่มีอยู่ในคำขอหรือการตอบสนอง
  

  ยกตัวอย่างเช่น: องค์ประกอบ pickupType ถูกลบ (หรือเปลี่ยนชื่อ) ออกจากคำขออัตราค่าบริการในเวอร์ชัน N

• เมื่อมีการลบวิธีการที่มีอยู่
  

  ยกตัวอย่างเช่น: เวอร์ชัน N จะไม่รองรับวิธีการสร้างและยกเลิกแท็กของ FedEx Express อีกต่อไป

• เมื่อองค์ประกอบที่มีอยู่ซึ่งเคยเป็นตัวเลือกหรือเงื่อนไขกลายเป็นองค์ประกอบบังคับในคำขอ
  

  ยกตัวอย่างเช่น: หมายเลขการจองคือองค์ประกอบบังคับสำหรับการส่งพัสดุ FedEx Express® Freight ในเวอร์ชัน N

• เมื่อโครงสร้าง API มีการเปลี่ยนแปลง
  

  ยกตัวอย่างเช่น: มีการจัดเรียงลำดับโครงสร้างคำขอและการตอบสนองใหม่

• เมื่อเกิดการเปลี่ยนแปลงด้วยรหัสข้อผิดพลาดและข้อความแสดงข้อผิดพลาด
  

  ยกตัวอย่างเช่น: เปลี่ยนแปลงรหัสข้อผิดพลาดจาก INCORRECT.WEIGHT เป็น WEIGHT.LIMIT.EXCEEDED

จะมีการปล่อยเลขเวอร์ชัน minor ของ API เมื่อไหร่

• เมื่อมีการเพิ่มค่าการแจกแจงใหม่
  

  ยกตัวอย่างเช่น: มีการเพิ่มข้อเสนอการขนส่งใหม่สำหรับองค์ประกอบ serviceType ในเวอร์ชัน N

• เมื่อมีการเพิ่มองค์ประกอบใหม่
  

  ยกตัวอย่างเช่น: องค์ประกอบทางเลือกใหม่ซึ่งรวบรวมหมายเลขโทรศัพท์ตัวแทนสำหรับการจัดส่งพัสดุระหว่างประเทศ

• เมื่อมีการเพิ่มวิธีการใหม่
  

  ยกตัวอย่างเช่น: วิธีในการแก้ไขเอกสารการค้าระหว่างประเทศหลังจากได้รับการอัปโหลดถูกเพิ่มในเวอร์ชัน N

• เมื่อองค์ประกอบที่มีอยู่ซึ่งเคยเป็นองค์ประกอบจำเป็นกลายเป็นองค์ประกอบทางเลือก
  

  ยกตัวอย่างเช่น: จะระบุ ID เอกสารหรือไม่ก็ได้ เนื่องจาก FedEx สามารถดู ID เอกสารได้จากข้อมูลของผู้ใช้