פיתוח חוזי API מבלי לאבד לקוחות

מה מדריך זה עוזר להשיג

• כתיבת החוזה
• הבהרת שגיאות
• בדיקת תאימות
• תכנון פרישה

בדיקה מהירה

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

שיטה שלב אחר שלב

1. 1

   צרכני מלאי

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

   תוצר: מפת תלות חוזה.

2. 2

   תיאור בקשות ותגובות

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

   תוצר: בדיקות חוזה ותאימות בגירסה.

3. 3

   ייצוב שגיאות.

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

   תוצר: קטלוג שגיאות שנבדק.

4. 4

   סיווג השינוי.

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

   תוצר: מטריצת תאימות והחלטת גרסה.

5. 5

   יצירת הודעות חזקות.

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

   תוצר: תרחיש הפעלה חוזרת ואישור.

6. 6

   שחרור עם נתיב יציאה

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

   תוצר: תוכנית העברה וראיות פרישה.

מדדי ניהול

טעויות נפוצות

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