9 שינויי API ששוברים את האפליקציה שלכם
"לא שברנו כלום. רק ניקינו את התגובה."
המילים האלו מובילות לעיתים קרובות לקריסות. אפליקציית מובייל קורסת. אינטגרציה עם שותף מחזירה נתונים לא תקינים. שיניתם את מבנה הנתונים שאחרים תלויים בו.
שינויים מסוכנים נראים לעיתים קרובות כמו "סידור". הם עוברים סקירות קוד ובדיקות. השבירה מתרחשת בקוד שאתם לא יכולים לראות.
הנה תשעה שינויים שמרגישים בטוחים, אך אינם כאלה.
שינוי שמות של שדות שינוי
userIdל-user_idלצורך עקביות שובר לקוחות. שינוי שם הוא למעשה מחיקה והוספה. החלק של המחיקה הוא זה ששובר דברים. Safe move: הוסיפו את השדה החדש. שמרו על הישן. סמנו אותו כ-Deprecated. הסירו אותו הרבה יותר מאוחר.הפיכת שדה לאופציונלי שדה שהיה קיים בעבר הוא כעת לעיתים
null. קוד הלקוח קורס כשהוא מנסה לעבד אותו. Safe move: התייחסו ל"קיים תמיד" כאל הבטחה. אם שדה הופך לאופציונלי, השתמשו בגרסה חדשה.הסרת שדות שאינם בשימוש אתם לא יכולים לראות איך הצרכנים שלכם משתמשים בנתונים שלכם. "לא בשימוש" פירושו רק שלא בשימוש מצידכם. Safe move: מדדו את השימוש בשדות בסביבת production לפני שתסירו משהו.
צמצום סוגי קלט שינוי
stringל-enumאו מספר ל-integerשובר בקשות. הרחבת קלט היא בטוחה. צמצום שלו הוא שינוי שובר. Safe move: הרפו רק את הקלטים שאתם מקבלים. הידוק דורש גרסה חדשה.שינוי ערכי ברירת מחדל שינוי ברירת מחדל מ-
falseל-trueמשנה התנהגות ללא שגיאה. זה שובר לוגיקה בשקט. Safe move: התייחסו לשינוי ברירת מחדל כאל שינוי שובר.הוספת שדות חובה הוספת
tenantIdוהפיכתו לחובה שוברת כל לקוח קיים. הם יקבלו שגיאת 400. Safe move: שדות חדשים חייבים להיות אופציונליים או להשתמש בגרסה חדשה.שינוי פורמטים של שגיאות שינוי מ-400 ל-422 או שינוי גוף השגיאה (error body) שובר את קוד הטיפול בשגיאות. Safe move: פורמטים של שגיאות הם חוזים (contracts). תנו להם מספר גרסה כמו לכל דבר אחר.
שינוי ערכי enum שינוי השם מ-"active" ל-"ACTIVE" שובר לקוחות. הסרת ערך שוברת לקוחות עם לוגיקה קשיחה. Safe move: ערכי enum הם לנצח. הוסיפו אותם בזהירות. לעולם אל תשנו את שמם או תסירו אותם ללא גרסה ראשית (major version).
שינוי משמעות הנתונים שינוי תאריך משניות Unix ל-ISO-8601 או שינוי פאגינציה (pagination) מ-offset ל-cursor שובר הכל. הבדל בסכימה (schema diff) אולי אפילו לא יתפוס את זה. Safe move: קבעו (pin) פורמטים באופן מפורש. השוו payloads אמיתיים, לא רק את המפרט (spec).
אל תסתמכו על תחושה. השוו כל שינוי מול ה-production contract ב-CI שלכם. אדם עלול לפספס שדה ששונה שמו. כלי diff לא יפספס.
מקור: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0