איך להשתמש ב-mock API כשמערכת היעד לא זמינה ל-POC

קטגוריה: אינטגרציות | תאריך: אוקטובר 2026

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

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

מהו mock API ומה הוא אמור להוכיח

mock API הוא endpoint שנראה לצרכן כמו API אמיתי: הוא מקבל בקשות לפי נתיב, method ו-schema מוגדרים ומחזיר status code ו-payload צפויים. אפשר לממש אותו ככלי ייעודי, שירות קטן או יכולת mocking שכבר קיימת בפלטפורמת ה-API של הארגון.

ב-POC טוב, ה-mock אמור לעזור לענות על שאלות ממוקדות:

• האם החוזה כולל את השדות שה-flow העסקי באמת צריך?
• האם המסך, ה-workflow או האוטומציה יודעים לבנות בקשה תקינה?
• האם התהליך מבחין בין הצלחה, דחייה עסקית וכשל טכני?
• האם אפשר לשמור correlation ID, סטטוס ונקודת חידוש?
• האם משתמש יכול להבין מה קרה ומה עליו לעשות כשיש חריג?
• האם שינוי צפוי בגרסת החוזה מזוהה לפני שהוא שובר את התהליך?

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

להתחיל מחוזה ולא מאוסף תשובות ידניות

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

• הנתיב וה-method, למשל POST ליצירת בקשה או GET לקריאת סטטוס.
• שדות חובה, טיפוסים, ערכים מותרים וכללי פורמט.
• מזהים עסקיים ומזהה idempotency אם הפעולה עשויה להישלח שוב.
• מבנה תשובת ההצלחה והמשמעות העסקית של כל סטטוס.
• מבנה שגיאה עקבי: קוד, הודעה, שדה בעייתי ו-correlation ID.
• צורת pagination או polling אם התוצאה אינה מוחזרת מיד.
• גרסה ומדיניות תאימות כאשר החוזה עדיין עשוי להשתנות.

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

המדריך על בדיקת API לפני POC מרחיב על בדיקת הפעולות שה-API חייב לאפשר. ה-mock מגיע אחרי שהוגדרה היכולת הנדרשת, גם אם המימוש האמיתי שלה עדיין אינו זמין.

לבחור תרחישים שמייצגים החלטות עסקיות

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

1. בקשה תקינה שמתקבלת ומחזירה מזהה.
2. שדה חובה חסר או ערך בפורמט שגוי.
3. רשומה שאינה קיימת במערכת היעד.
4. דחייה עסקית, למשל מעבר סטטוס שאינו מותר.
5. בקשה כפולה עם אותו idempotency key.
6. timeout או תשובת 503 זמנית.
7. תשובה איטית שמפעילה את מנגנון ההמתנה בממשק.
8. בקשה שהתקבלה לעיבוד ומסתיימת מאוחר יותר בהצלחה.
9. בקשה שמסתיימת מאוחר יותר בכשל עסקי.
10. payload עם שדה חדש שהצרכן עדיין אינו מכיר.

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

להפריד בין דחייה עסקית לכשל טכני

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

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

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

לדמות זמן ומצבים, לא רק payload

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

כדאי להגדיר מכונת מצבים קטנה:

received → processing → completed

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

כאשר ה-flow מבוסס אירועים, אפשר לדמות גם callback או webhook. חשוב לבדוק מה קורה אם האירוע מגיע פעמיים, באיחור או בסדר שונה. מאמרי webhook מול polling וטיפול בסדר אירועים מספקים עקרונות משלימים לתכנון הזה.

לא לדמות רק את המקרה שהצוות רוצה להציג

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

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

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

לשמור על הפרדה ברורה בין mock לחיבור אמיתי

קוד ה-POC צריך לאפשר להחליף endpoint וקונפיגורציה בלי לשנות את הלוגיקה העסקית. שמרו את כתובת השירות, סוג האימות ו-timeouts מחוץ לקוד, וודאו שהסביבה מציגה באופן ברור אם היא מחוברת ל-mock.

כדאי להוסיף הגנות:

• שם סביבה גלוי במסך ובלוגים.
• נתוני בדיקה שאינם נראים כמו רשומות ייצור אמיתיות.
• הרשאות נפרדות בין mock, בדיקות וייצור.
• איסור על שליחת credentials אמיתיים לשרת mock.
• חסימת route של mock מסביבת הייצור.
• correlation ID שמאפשר לזהות את מקור התשובה.

הפרדה זו מונעת מצב שבו תוצאת mock נשמרת כאילו הגיעה ממערכת ליבה, או שגרסת הדגמה נשארת בטעות בנתיב הייצור.

למדוד מה נבדק ומה עדיין פתוח

בסיום ה-POC, אל תסתפקו בהצהרה שה-flow עובד. צרו מטריצה קצרה:

| יכולת | נבדקה מול mock | דורשת מערכת אמיתית |

| --- | --- | --- |

| מבנה בקשה ותשובה | כן | אימות סופי |

| טיפול בשגיאות שהוגדרו | כן | מיפוי לשגיאות בפועל |

| UI ו-workflow | כן | בדיקה עם זמני אמת |

| authentication והרשאות | לא | כן |

| קצב, עומס ומגבלות | חלקית בלבד | כן |

| עקביות נתונים ומקור אמת | לא | כן |

| רשת, certificates ו-firewall | לא | כן |

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

תכנית מעבר מה-mock למערכת היעד

כדי שה-POC לא יישאר הדגמה מבודדת, הגדירו מראש את שלב ההחלפה:

1. מאשרים את החוזה מול בעלי מערכת היעד.
2. מריצים contract tests על ה-mock ועל סביבת הבדיקות האמיתית.
3. ממפים הבדלים בשדות, status codes, authentication והתנהגות זמן.
4. מתקנים את שכבת החיבור בלי לשנות את כל ה-flow.
5. מריצים את אותם תרחישים מול מערכת היעד עם נתוני בדיקה מאושרים.
6. מוסיפים בדיקות הרשאות, קצב, retry ו-reconciliation.
7. מתעדים אילו הנחות מה-mock הוכחו ואילו השתנו.

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

שאלות נפוצות

האם mock API יכול להחליף sandbox של ספק?

לא. mock מתאים לבדיקת חוזה ו-flow שבשליטת צוות ה-POC. sandbox אמיתי יכול לחשוף התנהגות, הרשאות ומגבלות שלא תועדו. כשקיים sandbox, אפשר להשתמש ב-mock לפיתוח מהיר וב-sandbox להוכחת החיבור.

האם צריך לבנות mock מלא לכל מערכת היעד?

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

מי צריך לאשר את התרחישים?

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

איך יודעים שהגיע הזמן לעבור לחיבור האמיתי?

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

להתחיל מפעולה אחת ושישה תרחישים

בחרו פעולה עסקית אחת שה-POC חייב לבצע. הגדירו עבורה חוזה, תשובת הצלחה, דחייה עסקית, validation error, timeout, retry ותוצאה אסינכרונית. חברו את המסך או ה-workflow ל-mock, ותעדו במפורש מה עדיין לא הוכח.

כך אפשר להתקדם גם כשהגישה למערכת היעד מתעכבת, בלי להציג הדגמה כתחליף לאינטגרציה אמיתית. Adaptico מסייעת בתכנון POC, APIs פנימיים ואינטגרציות למערכות ארגוניות, כולל חוזים, חריגים, בדיקות ומעבר מדורג לחיבור אמיתי. אפשר [ליצור קשר](/#contact) כדי למפות פעולה אחת ולבנות עבורה POC שניתן לאמת ולהרחיב.