גרסאות API - Versioning מוסבר¶

בניתם API, ואפליקציות מובייל, אתרים ושירותים חיצוניים כבר משתמשים בו. עכשיו אתם צריכים לשנות שדה, למחוק endpoint ישן, או לשנות את המבנה של תשובה - אבל אם תעשו את זה ישירות, כל הלקוחות הקיימים שמצפים למבנה הישן פשוט יישברו. Versioning הוא הפתרון לבעיה הזאת, ולמעשה כל API שחי מספיק זמן נאלץ להתמודד איתה.

למה בכלל צריך גרסאות¶

API הוא חוזה בין השרת לבין כל מי שקורא לו. ברגע שפרסמתם endpoint, אתם לא יכולים לדעת בוודאות מי כבר משתמש בו ואיך. שינוי "שבור" - כזה שמשנה מבנה תשובה קיים, מסיר שדה, או משנה התנהגות - יכול לגרום לאפליקציות אחרות לקרוס בלי אזהרה. versioning נותן דרך להכניס שינויים כאלה בלי לשבור מה שכבר קיים, על ידי הרצת כמה גרסאות של ה-API זו לצד זו.

שיטה ראשונה - גרסה בכתובת URL¶

הגישה הנפוצה והברורה ביותר היא לשים את מספר הגרסה ישירות בכתובת - למשל /v1/users ו-/v2/users. זה קל להבנה, קל לבדוק בדפדפן, וברור מיד לכל מי שקורא את הכתובת איזו גרסה הוא משתמש בה. החיסרון הוא שזה טכנית אומר שיש לכם כמה כתובות שונות שמצביעות על אותה משאב לוגי, מה שלפעמים נחשב פחות "נקי" מבחינת עקרונות REST.

גישה אחרת שומרת את הכתובת קבועה, ומעבירה את מספר הגרסה בתוך header ייעודי בבקשה - למשל Accept-Version. זה שומר על כתובות נקיות ועקביות לאורך זמן, אבל פחות נוח לבדיקה מהירה בדפדפן, ודורש שכל צרכן API יזכור להוסיף את ה-header הנכון, מה שקל יותר לפספס בטעות.

שיטה שלישית - גרסה בפרמטר שאילתה¶

גישה שלישית, פחות נפוצה אבל קיימת, מעבירה את הגרסה כפרמטר בכתובת - למשל users?version=2. זה נוח לבדיקות מהירות, אבל נחשב לרוב הכי פחות מסודר מבין השלוש, ופחות מקובל כסטנדרט בתעשייה.

מה קורה בפועל כשמוציאים גרסה חדשה¶

ברוב המקרים, אין צורך "לשכפל" את כל ה-API כשיוצרים גרסה חדשה. השינוי הוא לרוב ממוקד - endpoint אחד או שניים משתנים, ושאר ה-API נשאר זהה. הדפוס הנפוץ הוא לתחזק שכבת תאימות (compatibility layer) שממפה בין הגרסה הישנה לחדשה במקומות שהשתנו, כדי לא לשכפל לוגיקה שלא באמת השתנתה. זה חוסך הרבה עבודת תחזוקה כפולה.

הפסקת תמיכה - החלק שהכי קל לשכוח¶

הוצאת גרסה חדשה בלי תוכנית להוריד את הישנה יוצרת בעיה מצטברת - עם הזמן תומכים בשלוש, ארבע, חמש גרסאות שונות במקביל, וכל שינוי צריך להתבצע בכולן. תהליך הפסקת תמיכה תקין כולל הודעה מראש עם תאריך יעד ברור, תיעוד שמסביר איך לעבור לגרסה החדשה, ולעתים גם header אזהרה בתשובות מהגרסה הישנה שמזכיר ללקוחות שהיא בדרך החוצה. לתת ללקוחות זמן ומידע מספיק זה ההבדל בין הפסקת תמיכה מסודרת לבין שבירת מערכות של אחרים בלי אזהרה.

מתי בכלל לא צריך גרסה חדשה¶

לא כל שינוי דורש גרסה חדשה. הוספת שדה חדש לתשובה, למשל, היא בדרך כלל שינוי לא שובר - קליינטים ישנים פשוט מתעלמים מהשדה שלא הכירו. הכלל הפשוט הוא - אם קליינט קיים שממשיך להתנהג בדיוק כמו שהתנהג לפני השינוי, לא צריך גרסה חדשה. גרסה חדשה נדרשת רק כששינוי בהתנהגות הקיימת עלול לשבור מישהו שכבר סומך עליה.

איך לומדים לתכנן את זה נכון מהתחלה¶

לתכנן API עם versioning בראש כבר מהיום הראשון חוסך המון כאב ראש בהמשך. בקורס צד-שרת לומדים לבנות API עם ראייה קדימה, כולל תכנון לשינויים עתידיים בלי לשבור לקוחות קיימים.

מתלבטים איזו שיטת versioning מתאימה ל-API שלכם? זה בדיוק סוג השאלה שכדאי לשאול בקהילה שלנו.

הצטרפו לקהילה בדיסקורד

לסיכום¶

Versioning הוא לא פרט טכני שולי, הוא ההבדל בין API שאפשר לפתח ולשפר לאורך זמן לבין API שכל שינוי בו הוא סיכון לשבור מישהו. בין אם בוחרים גרסה בכתובת, ב-header, או בפרמטר, העיקרון החשוב באמת הוא לתכנן מראש איך שינויים עתידיים ייכנסו למערכת בלי להפתיע אף אחד שכבר משתמש בה.