ניהול גרסאות

במדריך הזה מוסבר איך Merchant API מטפל בניהול גרסאות, בהפצות ובמחזור החיים של הגרסאות השונות שלו.

תכנית ניהול גרסאות

ב-Merchant API נעשה שימוש באסטרטגיית ניהול גרסאות ברמת ה-API המשני. המשמעות היא שלכל API, למשל Products ב-Merchant API, יהיה מחזור חיים משלו של גרסה.

פורמט ומיקום של מספור גרסאות

• גרסאות יציבות של ממשקי משנה של API: אם ממשק משנה של API הוא בגרסה יציבה, כל ה-methods שלו הם בגרסה יציבה. גרסה יציבה של API משני מיוצגת כ-vX (לדוגמה, v1, ‏ v2). אלה גרסאות ראשיות שמוכנות לייצור.

• גרסאות אלפא של ממשקי משנה של API: אם ממשק משנה של API הוא בגרסת אלפא, כל השיטות שלו הן בגרסת אלפא. גרסת אלפא של API משני מיוצגת כ-vXalpha (לדוגמה, v1alpha, ‏ v2alpha). הן מכילות תכונות ניסיוניות בשלבי פיתוח ראשוניים שמיועדות לבדיקה ולשיפור מהיר. גרסאות אלפא לא מגיעות עם הבטחת יציבות, אין להן משך חיים מוגדר ואפשר לשנות אותן או להפסיק את השימוש בהן בהתראה של 30 יום.

שינויים בגרסה

• עלייה במספר הגרסה הראשית (לדוגמה, מגרסה v1 לגרסה v2): שינויים כאלה מצביעים על שינויים שעלולים לגרום לכשלים ועל שינויים שלא תואמים לאחור, ולכן נדרשת פעולה מצד המפתח. רק שינויים שוברים בממשקי משנה יציבים של API יקבלו מספר גרסה חדש. לדוגמה, v1 ל-v2.

• שינויים קלים: תוספות או תיקונים שתואמים לאחור מוצגים כשינויים בגרסה הראשית הקיימת. שינויים כאלה יפורטו בהערות על הגרסה הראשית. תוספות שלא גורמות לשינויים משמעותיים ב-API משני יפורסמו בערוץ אלפא של הגרסה היציבה האחרונה או ישירות בגרסה היציבה האחרונה.

מדיניות בנושא הוצאה משימוש

מדי פעם אנחנו מוציאים משימוש גרסאות ישנות יותר של Merchant sub-API. אנחנו מתחייבים לחלון זמן של 12 חודשים להוצאה משימוש של גרסאות יציבות ראשיות (vX), החל מההודעה הרשמית על הוצאה משימוש.

לדוגמה, אם נוציא משימוש את גרסה 1 של Products sub-API ב-15 בינואר 2026, היא תושבת ב-15 בינואר 2027 או לאחר מכן. אחרי התאריך הזה, לא תהיה יותר אפשרות להשתמש בגרסה הקודמת של ה-API המשני.

גרסת משנה של API וסטטוס מחזור החיים

בטבלה הבאה מפורטות הגרסאות האחרונות של כל אחד מממשקי המשנה של Merchant API:

שיטות מומלצות

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