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

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