בחינה מנקודת מבט הלקוח
הטבלה היא כלי סקירה, לא הבטחה כללית. שדה נוסף עלול לפגוע בקורא קשיח וערך מנייה חדש בטיפול ממצה. מנו לקוחות, ספריות והנחות.
| שינוי | סיכון לבדיקה | ראיה נדרשת |
|---|---|---|
| מחיקה או שינוי שם שדה | הקריאה מפסיקה לעבוד | מעבר מפורש ובדיקות לקוח. |
| הוספת שדה רשות | קורא קשיח או התנגשות שמות | בדיקת צרכנים קיימים. |
| ערך חדש בתשובה | טיפול ממצה חסר | התנהגות לערך לא מוכר. |
| שינוי ברירת מחדל | תוצאה עסקית שונה | השוואה ללא ערך מפורש. |
ארגון קיום במקביל
- תארו מבנים ישנים וחדשים, ברירות מחדל, שגיאות, דפדוף והרשאות. בצעו בדיקות חוזה עם תרחישים מייצגים.
- בחרו מנגנון בחירת גרסה מפורש. הבדילו בין גרסת שירות לגרסת מסמך OpenAPI ובדקו מטמונים ושערים.
- פרסמו לוח זמנים, מדריך ואיש קשר. מדדו שימוש בפועל באופן מידתי והכינו חזרה התואמת לנתונים.
להבדיל בין הוצאה משימוש לכיבוי
Deprecation מסמן משאב שהוצא משימוש; Sunset עשוי להודיע מתי צפויה אי־זמינות. הכותרות אינן מעבירות לקוחות. לפני הסרה בדקו צרכנים שנותרו, חובות ותהליך שחזור.
מקורות ראשוניים
- Google AIP-180 — Backwards compatibility [EN]
- IETF RFC 9745 — Deprecation [EN]
- IETF RFC 8594 — Sunset [EN]
גרסה לפי השפעת הצרכן
הוספת מספר לכתובת 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 s | HTTP 202 · pending | התקבלה לעיבוד; טרם אושרה תוצאה סופית. |
| +5 s | HTTP 200 · running | קריאת המצב הצליחה; המשימה עדיין פועלת. |
| +6 s | HTTP 200 · cancel_requested | בקשת העצירה נרשמה; הביטול טרם אושר. |
| +7 s | HTTP 200 · succeeded | העיבוד הושלם לפני הביטול. הציגו הצלחה מאושרת ובדקו השפעות; אל תדווחו על ביטול. |
האם 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. שיטה קשורה: קריאת המדריך המעשי.
הוצאת 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
