9 การเปลี่ยนแปลง API ที่ทำให้แอปของคุณพัง

"เราไม่ได้ทำอะไรพัง เราแค่จัดระเบียบ response ให้สะอาดขึ้น"

คำพูดเหล่านี้มักนำไปสู่การแครช (crash) แอปมือถือใช้งานไม่ได้ การเชื่อมต่อกับพาร์ทเนอร์ส่งข้อมูลขยะกลับมา คุณได้เปลี่ยนรูปแบบข้อมูลที่คนอื่นต้องใช้งานอยู่

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

นี่คือ 9 การเปลี่ยนแปลงที่ดูเหมือนจะปลอดภัย แต่จริงๆ แล้วไม่ใช่

• การเปลี่ยนชื่อฟิลด์ (Renaming fields) การเปลี่ยน userId เป็น user_id เพื่อความสม่ำเสมอจะทำให้ client พัง การเปลี่ยนชื่อคือการลบและเพิ่มใหม่ ส่วนการลบคือสิ่งที่ทำให้คนอื่นเดือดร้อน วิธีที่ปลอดภัย: เพิ่มฟิลด์ใหม่เข้าไป เก็บฟิลด์เก่าไว้ก่อน แล้วค่อยประกาศเป็น deprecated จากนั้นค่อยลบออกในภายหลัง

• การทำให้ฟิลด์เป็นแบบ optional (Making a field optional) ฟิลด์ที่เคยมีอยู่เสมอ ตอนนี้บางครั้งกลับเป็น null โค้ดฝั่ง client จะแครชเมื่อพยายามประมวลผลมัน วิธีที่ปลอดภัย: ให้ถือว่าการที่ฟิลด์ "มีอยู่เสมอ" คือคำสัญญา หากฟิลด์นั้นต้องกลายเป็น optional ให้ใช้เวอร์ชันใหม่แทน

• การลบฟิลด์ที่ไม่ได้ใช้งาน (Removing unused fields) คุณไม่สามารถรู้ได้ว่าผู้ใช้งานข้อมูลของคุณนำไปใช้อย่างไร คำว่า "ไม่ได้ใช้งาน" หมายถึงแค่ว่า "คุณไม่ได้ใช้งานมัน" เท่านั้น วิธีที่ปลอดภัย: วัดผลการใช้งานฟิลด์ในระบบ production ก่อนที่จะลบอะไรออก

• การจำกัดประเภทข้อมูลขาเข้า (Narrowing input types) การเปลี่ยนจาก string เป็น enum หรือจาก number เป็น integer จะทำให้ request พัง การขยายประเภทข้อมูล (widening) นั้นปลอดภัย แต่การจำกัดให้แคบลง (narrowing) คือการเปลี่ยนแปลงที่ทำให้ระบบพัง (breaking change) วิธีที่ปลอดภัย: อนุญาตให้ input กว้างขึ้นเท่านั้น การทำให้เข้มงวดขึ้นต้องใช้เวอร์ชันใหม่

• การเปลี่ยนค่าเริ่มต้น (Changing default values) การเปลี่ยนค่าเริ่มต้นจาก false เป็น true จะเปลี่ยนพฤติกรรมของระบบโดยไม่มี error เกิดขึ้น ซึ่งจะทำให้ logic พังแบบเงียบๆ วิธีที่ปลอดภัย: ให้ถือว่าการเปลี่ยนค่าเริ่มต้นคือการเปลี่ยนแปลงที่ทำให้ระบบพัง (breaking change)

• การเพิ่มฟิลด์ที่จำเป็น (Adding required fields) การเพิ่ม tenantId และกำหนดให้เป็นฟิลด์ที่จำเป็น (required) จะทำให้ client ทุกรายที่ใช้งานอยู่พัง เพราะพวกเขาจะได้รับ error 400 วิธีที่ปลอดภัย: ฟิลด์ใหม่ต้องเป็นแบบ optional หรือไม่ก็ต้องใช้เวอร์ชันใหม่

• การเปลี่ยนรูปแบบ error (Changing error formats) การเปลี่ยนจาก 400 เป็น 422 หรือการเปลี่ยน error body จะทำให้โค้ดส่วนจัดการ error พัง วิธีที่ปลอดภัย: รูปแบบ error คือข้อตกลง (contract) ให้จัดการเรื่องเวอร์ชันเหมือนกับส่วนอื่นๆ

• การแก้ไขค่า enum (Modifying enum values) การเปลี่ยนชื่อจาก "active" เป็น "ACTIVE" จะทำให้ client พัง การลบค่าใดค่าหนึ่งออกจะทำให้ client ที่มี logic แบบเข้มงวดพัง วิธีที่ปลอดภัย: ค่า enum คือสิ่งที่คงอยู่ตลอดไป ให้เพิ่มอย่างระมัดระวัง อย่าเปลี่ยนชื่อหรือลบออกโดยไม่มีการขึ้นเวอร์ชันหลัก (major version)

• การเปลี่ยนความหมายของข้อมูล (Changing data meaning) การเปลี่ยนรูปแบบวันที่จาก Unix seconds เป็น ISO-8601 หรือการเปลี่ยน pagination จาก offset เป็น cursor จะทำให้ทุกอย่างพัง การเช็ค schema diff อาจตรวจไม่พบสิ่งเหล่านี้ด้วยซ้ำ วิธีที่ปลอดภัย: กำหนดรูปแบบให้ชัดเจน (Pin formats explicitly) และเปรียบเทียบจาก payload จริง ไม่ใช่แค่ดูจาก spec

อย่าใช้เพียงความรู้สึก ให้เปรียบเทียบทุกการเปลี่ยนแปลงกับ production contract ใน CI ของคุณ มนุษย์อาจมองข้ามฟิลด์ที่ถูกเปลี่ยนชื่อ แต่เครื่องมือ diff จะไม่พลาด

ที่มา: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0