פיתוח אפליקציות עם API מאפשר ללקוח בטלפון לקרוא ולעדכן מידע ממערכת אחרת לפי חוזה מוסכם. חוזה טוב קובע מה נשלח, מי רשאי לשלוח, מה השרת מחזיר ואיך ממשיכים כשיש שגיאה או רשת חלשה. למשל, אפליקציה להזמנות צריכה לדעת אם הזמנה כבר נוצרה, אם עוד לא התקבלה או אם תהליך אחר שינה אותה. מסמך עם כתובות בלבד אינו מספק את המידע הזה. כדאי לבחור פעולה ולתכנן את התוצאה כפי שהיא נראית במכשיר ובמערכות התפעול.
נשתמש בדוגמה של מערכת הזמנות מחסן. נציג בוחר פריטים, מבקש זמינות ושולח הזמנה. במקביל מערכת אחרת עשויה לשנות מחיר, מלאי או הרשאת לקוח. אפליקציה טובה יכולה להציג מה ידוע בזמן הבחירה, לקבל תוצאה כאשר העסקה נעשית ולהסביר מה דורש תיקון. בעזרת תכנון מינימלי של חוזה אפשר לזהות מה קורה בשגרה ומי אחראי בתקלה לפני שמשחררים את הגרסה הראשונה.
מה כולל חוזה API שימושי?
הגדירו פעולה, קלט, הסבר שדות ותוצאות. לדוגמה, פעולת פתיחת הזמנה מקבלת מזהה לקוח, פריטים, כמויות ומזהה ניסיון. התוצאה יכולה לכלול מספר הזמנה ומצב. כאשר מלאי אזל, התשובה צריכה לעזור לאפליקציה לדעת איזה פריט דורש בחירה חדשה. הוסיפו דוגמה מלאה, תשובה חלקית ונתון חסר או בלתי תקין. בתיאור ערכים, ציינו מטבע, יחידות, אזור זמן וכל כלל שמשפיע על הדרך שבה המשתמש מבין תשובה.
כלי כמו OpenAPI יכול לתאר פעולות ותבניות ולתת לצוות נקודת ייחוס משותפת. בנקודה שבה יש החלטה עסקית, הוסיפו דוגמת תהליך. ממשק יכול לציין שיש שדה ״סטטוס״, אבל צריך להגדיר מתי סטטוס משתנה, מי שולט ולמי פונים אם הוא לא עדכני. אפשר להוסיף טבלת מיפוי או כלל כתוב. מפתח אפליקציה ומפתח השרת צריכים להבין אותה דוגמה בלי שיחה. בעבודה עם ספק חיצוני, קבעו מי מודיע על שינוי ואיך בודקים לפני פרסום.
| חלק | החלטה | בדיקה |
|---|---|---|
| קלט | שדות חובה, משמעות ומזהים | ערך חסר, לא תקין או פעמיים |
| גישה | מי רשאי לקרוא ולשנות | משתמש עם הרשאה וחשבון אחר |
| מצב | היכן אמת ומה מציגים בזמן המתנה | תגובה שהתעכבה וניסיון חוזר |
| כשל | משמעות ותוצאה שניתן להציג | תקלה זמנית או סירוב עסקי |
| גרסה | מה נשאר תואם בתקופת מעבר | אפליקציה ותיקה מול שרת מעודכן |
איך בודקים שהגישה נכונה בכל בקשה?
התחברות נותנת למערכת דרך לזהות משתמש. בכל בקשה צריך לבדוק מה מותר לו לפי הארגון, התפקיד והמשאב. לדוגמה, משתמש שמגיע מכרטיס הזמנה ששותף לא אמור לקרוא הזמנה שאינה שלו רק כי הוא הצליח להיכנס. בדקו את החיפוש, הקריאה הישירה והפעולות המעדכנות. עברו על שתי דוגמאות באותו תפקיד בשני לקוחות, ונסו מעבר בזמן שהמסך עדיין מציג מידע קודם. כך בודקים הרשאה גם כאשר מסך או קישור אינם פועלים במסלול הרגיל.
לספק חיצוני אפשר להגדיר גישה שמתאימה לפעולה מסוימת ולסביבה מסוימת. הימנעו מהטמעת סודות שירות בתוך קוד שמופץ למכשיר. קבעו איך מחליפים גישה ואילו פרטים נשמרים בדוחות. כשמשתמש פנה לתמיכה, לרוב אפשר להסתמך על מזהה בקשה, שעה וגרסה במקום לשמור מידע שלא דרוש. בדקו גם אם משימה אוטומטית קוראת משאב עבור לקוח נכון ואיך היא משדרת פער במקום להסתיר שגיאה.
איך בונים סנכרון ומנסים שוב בלי ליצור כפילות?
שמרו מזהים שאפשר להשתמש בהם לאורך תהליך. כאשר האפליקציה שולחת הזמנה והרשת מתנתקת, אין ודאות אם השרת כבר קיבל. אם אפשר להשתמש במזהה ניסיון קבוע, השרת יכול להחזיר את התוצאה של פעולה שכבר נקלטה במקום לפתוח חדשה. הגדירו כמה זמן נשמר הזיהוי ואיך מתנהגים כשאותו מזהה מגיע עם תוכן אחר. בדקו עבודה עם רשת חלשה, חזרה למסך לאחר סגירה ומצב שבו טלפון נוסף פועל במקביל.
תכננו איזו תשובה תגרום לניסיון חוזר ואיזו דורשת פעולה אחרת. בעיה זמנית יכולה להצדיק המתנה וניסיון מאוחר יותר. אם אין הרשאה או שהנתון לא תקין, צריך להציג שאלה או פעולה למשתמש. כאשר תור מקומי ממתין, הציגו אם הוא נשמר ומה יקרה אחרי חיבור. חלק מן הנתונים יכולים להיקרא מהמטמון לפני שעודכנו. שימו לב לשעת תוקף ולדרך שבה תצוגה מסמנת תוצאה ישנה. כך העובד יודע מה עבר לשרת ומה עדיין לא.
איך בודקים אוסף בקשות ומסלולי כשל?
הכינו אוסף עם פתיחת הזמנה, בדיקת מצב, עדכון וביטול. הוסיפו חשבון שאינו רשאי, כמות שעברה מגבלה ושינוי שבוצע בשרת. בדקו תשובת מערכת, תוכן ושיוך לפני שתופסים את התוצאה מהמסך. בדיקות מסודרות צריכות לעבור באותה גרסה ולהראות מה יצא שונה. אם מספר נתונים תלוי בבקשה קודמת, שמרו דוגמת התחלה שניתן להריץ מחדש בלי להסתמך על פעולות קודמות של צוות אחר.
סרטון Postman על עבודה עם מפרטי API
בסרטון מוצג שימוש במפרטים. לאחר הצפייה, נסו לשייך לכל פעולה שמופיעה באפליקציה גם תשובה חיובית וגם מצב שבו המשתמש צריך לדעת איך להמשיך.
איך תומכים בשינוי גרסה בלי להפסיק שימוש קיים?
קבעו איזה קוד ימשיך לעבוד ומתי יידרש ליצור גרסה חדשה. הוספת שדה יכולה לעבור בצורה פשוטה, אבל שינוי משמעות או הסרה של שדה דורשים תשומת לב לתאימות. בדקו מה רואה אפליקציה ותיקה כאשר שרת מוסיף מצב חדש. אפשר להציג תיאור כללי לפי החלטה עסקית, להפעיל יכולת רק לגרסאות שתומכות או לתכנן מעבר בשלבים. נסו את החיבור עם מכשיר שעדיין מריץ גרסה קודמת ומחובר לאותו משתמש.
לפני שינוי, תעדו איזה צד צריך לצאת קודם, מה קורה לאירועים שממתינים ומה ניתן לראות בדוח. אם הוספתם מידע חובה, בדקו מה קורה עם טיוטות שנשמרו לפני כן. מצב פשוט של חוסר מידע יכול להפוך לכשל ארוך בגרסה שאינה יודעת להציגו. לכן קבעו מועד לבדיקה משולבת, ותנו למוקד דרך להבין איזה מספר גרסה מותקן. לאחר שחרור עקבו אחר שגיאות ופעולות שלא הסתיימו, לפי הפלטפורמה והגרסה.
איך נראה תרחיש עם פתיחת הזמנה, שינוי ומצב מתנגש?
בשלב ראשון אפליקציה קוראת פריטים לפי לקוח. חלק מהנתונים, כמו תיאור, עשויים להישאר מקומיים לזמן מוגדר. זמינות ומחיר נבדקים בעת הפעולה שנקבעה. כשהנציג בוחר שלוש יחידות, השרת יכול להחזיר שהכמות השתנתה ושקיימות שתיים. האפליקציה מציגה מה נקרא, מה אפשר להחליף ואם צריך לאשר מחדש. כך תהליך עסקי נשאר ברור גם כאשר מידע הגיע מאוחר יותר. הבדיקה צריכה לכלול דרך להגיע שוב לאותה הזמנה ולראות את התוצאה.
בשלב שני מנהל במחסן מעדכן את ההזמנה ומישהו במובייל מנסה להוסיף פריט לפי התצוגה שקרא קודם. קבעו מה מחייב קריאה עדכנית, איזה שינוי אפשר לשלב ואיזה דורש שאלה. אחד הפתרונות הוא לשמור גרסת רשומה שהלקוח מציין בזמן עדכון. אם הגרסה כבר אינה עדכנית, המערכת מסבירה מה השתנה ומאפשרת לעיין בתוצאה הנוכחית. זהו כלל שהצד הטכני צריך לתכנן ביחד עם הארגון, כי לא כל הבדל מחייב הכרעה באותו אופן.
תרחיש שלישי הוא קריאה לרשימה גדולה. נציג צריך לחפש לקוח ולראות את המספר האחרון של רשומות. אפשר להגדיר עמודים, סדר מיון ומזהה עקבי. בדקו איך הלקוח מגיב כאשר נוסף פריט בזמן שהוא עובר לדף הבא. כדאי להימנע מהנחה שהרשימה תמיד קטנה. חזרו על המדידה עם נתונים גדולים יותר ומכשיר איטי. אם דרוש רק חלק מהשדות, קבעו מה נחוץ להצגה. כך חיבור שנראה תקין בדוגמה קטנה נשאר שמיש בקצב של העסק.
מה מגדירים לגבי הודעות שגיאה?
הפרידו בין קוד טכני, משמעות עסקית והודעה. קוד קבוע יכול לשמש לדוחות, משמעות יכולה להגיד שהמלאי שונה וההודעה למשתמש מציעה לבחור מחדש. שימוש באותה הודעה לכל כשל גורם לאנשים לנסות שוב אפילו אם חסרה הרשאה. בדקו שהאפליקציה יכולה לזהות סוג שגיאה ושהשרת אינו מחזיר מידע פנימי בצורה שאינה מתאימה לקהל. עבור תקלות לא מוכרות, החליטו מה אפשר להגיד וכיצד נציג שירות ימצא את המקרה. השאירו תאריך ומזהה שמתאים למספר מערכות.
שימו לב למקרה שבו לא קיבלתם תשובה. יש הבדל בין שרת שהחזיר כשל לבין חיבור שהסתיים אחרי זמן המתנה. אם אתם יודעים שבקשה לא התקבלה, אפשר לאפשר שליחה. אם לא ידוע אם התקבלה, עדיף לבדוק מצב בעזרת מזהה. לפני שמוסיפים כפתור ״נסה שוב״ קבעו איזה צעד הוא מבצע והאם נשאר מידע שאינו עדכני. תרגיל שימוש טוב נותן לאדם לראות הודעה ולספר מה הוא חושב שהתרחש. אם הבנתו שונה ממה שהשרת יודע, שנו את המסר.
איך מחברים שירות של ספק חיצוני?
ראשית בקשו מידע על כתובות, זהות, הגדרת סביבה ותזמון שינויים. תרגלו פעולה רגילה, מגבלת קצב ומצב שבו מקבלים תשובה חלקית. אם נתונים מעודכנים אחת לכמה דקות, הציגו זמן רלוונטי וכתבו מה קורה אם צריך תגובה מיידית. החלטה להתבסס על ספק יכולה לחסוך עבודה, ובמקביל דורשת להבין מה קורה כשמגלים ששדה אינו זמין. תעדו למי פונים ועל סמך איזה נתון אפשר לשחזר תוצאה. אל תניחו שהדוח של הספק מכיל מידע שבאמת דרוש לאדם בצד העסק.
אפשר ליצור שכבה שמתרגמת בין האפליקציה לבין הפורמט של ספק. במקרה כזה, נציג רואה אותן הודעות גם אם מחליפים ספק או משנים שדה. בדקו איזה מידע נדרש לשמור, מה עובר לאחסון זמני ואיזה שינוי מגיע במועד שהאפליקציה עדיין לא התעדכנה. בתרחיש בדיקה נסו לעצור את החיבור, לשמור תור ולחזור. אחרי שחוזר שירות, בדקו איזה מידע הועבר ומי מקבל הודעה על תוצאה שלא בטוח שהתקבלה. כך תכנון הממשק מתואם עם אחריות תפעולית.
איך בודקים את התוצאה על מכשיר ועל השרת?
הריצו את אותו תרחיש בשני מקומות. בצד השרת בדקו קוד תגובה, תוכן ומידע שנשמר. במכשיר בדקו מה אדם הבין ומה אפשר לעשות. תנו לבודק חשבון עם גישה וחשבון מוגבל, והוסיפו גרסה קודמת. כשנדרש עדכון למידע רגיש, בדקו שההרשאה השתנתה בשני המקומות. לפני העברה לתפעול, קבעו תהליך שעובר עד הדוח. אם נציג יכול למצוא רק מספר חלקי, תנו לו דרך לקשר למצב אחר או להבין איזה ספק מחזיק את המידע.
בחרו מדדי זמן וכשל לפי הפעולה. אם הזמנה נפתחת אחרי שלוש דקות, ייתכן שהשירות עושה עבודה ברקע וצריך שהלקוח יידע מה קורה. אפשר להראות עדכון זמני ולחזור לתוצאה. אם זמן התגובה משפיע על כל חיפוש, שווה להבין אם הבעיה בקצב השרת, בנתונים שמבקשים או בתצוגה. קבעו תאריך לבדיקה חוזרת אחרי שחרור, והשתמשו בגרסה, דגם ותנאי רשת. השילוב מסביר מה השתפר ואם צריך לשנות את החוזה.
מה מוסרים לצוות הבא?
מספקים מפרט, תרחישי בדיקה, הסבר על הרשאות, גרסאות ושגיאות. שמרו בעל אחריות לכל מערכת וחיווי למקרה של שינוי בכתובת או בשדה. בקשו מאדם חדש לפתוח הזמנה, לגרום לשגיאה ולמצוא את התוצאה בדוחות. אם הוא מתקשה להבין האם אותה פעולה נשמרה, הוסיפו תיעוד או מבחן. מערכת שמחברת כמה מוצרים תמשיך לקבל עדכונים. מסירה קצרה ומעשית מאפשרת לבדוק אם חיבור חדש מתנהג לפי הכללים לצד העבודה שכבר קיימת.
איך קובעים בדיקות שחוזרות אחרי שינוי בממשק?
מסרו אוסף שאפשר להריץ בסביבה נפרדת. הגדירו מה נוצר במסלול, כיצד נפטרים מנתוני בדיקה ומה נכון לשמור בתוצאות. בקשה אחת בוחנת הצלחה, אחרת הרשאה וגישה, ושלישית תרחיש שבו עדכון הוחזר באיחור. אם יש כמה גרסאות, שמרו דוגמאות למידע שקודם היה תקף והוסיפו בדיקה להבדל. לבסוף תנו לנציג לפתוח דוח ולזהות איזו מערכת קיבלה את הפעולה. כך שינוי קטן במפרט לא מכסה על בעיה שנראית רק במוצר.
במקרים שבהם כמה צוותים תלויים בחיבור, תנו להם זמן לבדוק מעבר. אפשר לפרסם דוגמה לתשובה החדשה, לציין מועד כניסה ולשמור מסלול לרכיבים שעוד לא התעדכנו. החזרה למצב מוכר תלויה גם בנתונים שנוצרו בין הגרסאות. קבעו מי רשאי לשנות תצורה, ואילו בדיקות יש לבצע לפני שמחזירים קוד קודם. תרגיל שכולל תקלת ייצור מדומה עוזר לשמור תוצאות קיימות גם כאשר צורת העבודה משתנה.
אחרי הפצה עקבו אחר זמן, כשל ותוצאה לפי פעולה. מדגם של בקשות מדווח על חיבור שעבד, והשלמת פעולה במכשיר מראה אם העבודה כולה הצליחה. השוו את שתי התוצאות אחרי שינוי כדי לראות איזה חלק עדיין נדרש לתחזוקה.
שאלות נפוצות על פיתוח עם API
האם כדאי להתחיל מכתיבת API מלא?
התחילו מפעולה אחת ותרחיש כשל, ואז מכסים תהליך נוסף. חוזה קטן שנבדק מול המכשיר עוזר לשני הצוותים לעבוד במקביל.
מה קורה אם אין חיבור בזמן שליחה?
קובעים אם שומרים ניסיון, מה רואים ומתי מנסים שוב. לאחר חזרת הרשת מוודאים שהשרת מזהה אם הפעולה כבר נקלטה.
איך יודעים אם המידע עדכני?
מגדירים מקור ותוקף. אפשר להציג מועד עדכון ולהסביר אם מוצגים נתונים מקומיים. במצבים רגישים בודקים התאמה לפני פעולה.