גרסאות API: הכנת מעבר תואם

בקצרה

החלפת מספר אינה מגינה מעצמה על לקוחות. תאימות כוללת הודעות והתנהגות שעליהן מסתמכים צרכנים אמיתיים.

עמדת בדיקת רכיבים אלקטרוניים ללא אנשים
במאמר זה

בחינה מנקודת מבט הלקוח

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

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

ארגון קיום במקביל

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

להבדיל בין הוצאה משימוש לכיבוי

Deprecation מסמן משאב שהוצא משימוש; Sunset עשוי להודיע מתי צפויה אי־זמינות. הכותרות אינן מעבירות לקוחות. לפני הסרה בדקו צרכנים שנותרו, חובות ותהליך שחזור.

מקורות ראשוניים

גרסה לפי השפעת הצרכן

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

  • מלאי לקוחות פעילים ושימוש שנצפה.
  • בדיקת גרסאות לקוח ישנות יותר מול החוזה החדש.
  • פרסום תקופת דו-קיום ובדיקת שימוש לפני פרישה.

מקור ראשוני: IETF RFC 9457 — Problem Details for HTTP APIs. שיטה קשורה: קריאת המדריך המעשי.

משימות API אסינכרוניות

קבלת בקשה אינה מוכיחה שהעבודה הסתיימה.

  • חשבון, פעולה ומזהה לשימוש חוזר
  • מצב, זמן, מרווח ותפוגה
  • פלט, שגיאה, ביטול והשפעות שנותרו
  • משימה מורשית אחת ותוצאה שנבדקה לאחר ניתוק

מקרה קבלה שניתן לשחזר

דוגמה בדיונית: הנתונים אינם מתארים לקוח או תוצאה שנצפתה.

הצגת נתוני המקרה
{
    "job_id": "J-42",
    "timeline": [
        {
            "elapsed_seconds": 0,
            "http": 202,
            "state": "pending"
        },
        {
            "elapsed_seconds": 5,
            "http": 200,
            "state": "running"
        },
        {
            "elapsed_seconds": 6,
            "http": 200,
            "state": "cancel_requested"
        },
        {
            "elapsed_seconds": 7,
            "http": 200,
            "state": "succeeded"
        }
    ]
}

החלטה צפויה

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

בקשת הביטול הגיעה מאוחר מדי

תרחיש בדוי: אותה משימה J-42, שניות מאז השליחה. שמות המצבים שייכים לחוזה שבדוגמה; HTTP אינו מחייב אותם.

זמןתגובה ומצבמסקנה מבוססת
+0 sHTTP 202 · pendingהתקבלה לעיבוד; טרם אושרה תוצאה סופית.
+5 sHTTP 200 · runningקריאת המצב הצליחה; המשימה עדיין פועלת.
+6 sHTTP 200 · cancel_requestedבקשת העצירה נרשמה; הביטול טרם אושר.
+7 sHTTP 200 · succeededהעיבוד הושלם לפני הביטול. הציגו הצלחה מאושרת ובדקו השפעות; אל תדווחו על ביטול.

Microsoft — Asynchronous request-reply

האם 202 מוכיח שהעבודה תסתיים?

לא. הוא מאשר קבלה לעיבוד ולא את התוצאה הסופית. בדקו את מצב הפעולה.

מקור ראשוני: MDN — 202 Accepted. שיטה קשורה: קריאת המדריך המעשי.

עדכוני תוכנה: לבדוק שינוי בזהות החותם

לקבוע אם תוצר חתום עדיין תואם ליצרן, לתהליך הבנייה ולגרסה שאושרו.

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

מקרה קבלה שניתן לשחזר

דוגמה בדיונית: הנתונים אינם מתארים לקוח או תוצאה שנצפתה.

הצגת נתוני המקרה
{
    "signature_valid": true,
    "digest_matches": true,
    "expected_signer": "approved-publisher",
    "observed_signer": "different-publisher",
    "expected": "hold_for_independent_confirmation"
}

החלטה צפויה

דוגמה בדיונית: הגיבוב מתאים והחתימה תקינה, אך החותם שונה מהמאושר. ההתקנה ממתינה לאישור בלתי תלוי של השינוי.

SLSA v1.2 — Verifying artifacts

מקור ראשוני: SLSA v1.2 — Verifying artifacts. שיטה קשורה: קריאת המדריך המעשי.

הוצאת API משימוש

הערות המקורות המפורטות זמינות באנגלית במהדורה זו.

Plan retirement beyond the version number

A published version does not say when consumers need to migrate. Connect deprecation announcements, retirement dates and existing-client tests.

  • Distinguish Deprecation, Sunset and policy links.
  • Check that Sunset does not precede Deprecation when both dates are provided.
  • Measure remaining consumers and validate the replacement before cutover.

Compare deprecation and retirement announcements →

IETF · RFC 9745 · Deprecation · Standards Track · March 2025 · §2–5 · consulted 2026-10-23

IETF · RFC 8594 · Sunset · Informational · May 2019 · §3–5, §8 · consulted 2026-10-23