להפוך אקסל לאתר – חלק 5: חיבור האפליקציה ל-API חיצוני

מה עושים בשיעור הזה

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

יש שתי סיבות עיקריות לעשות את זה. הראשונה: לקבל מידע משירות חיצוני, או לבקש ממנו לבצע פעולה בשבילנו. לזה קוראים API. השנייה: לקבל מידע שהעולם החיצוני “דוחף” אלינו מיוזמתו. לזה קוראים Webhooks, ונגיע אליהם בהמשך הקורס.

כדי שזה לא יהיה תיאורטי, נבנה את זה בשלבים, סביב דוגמה אחת:

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

מה זה API, ומה זה Open-Meteo

API הוא קיצור של Application Programming Interface. בשפה פשוטה: דרך שבה תוכנה (ולא בן אדם) ניגשת לשירות חיצוני, כדי לקבל ממנו מידע או לבקש ממנו לעשות משהו.

לתרגול נשתמש ב-Open-Meteo (open-meteo.com). אני אוהב אותו בדיוק לשיעור כזה: הוא נותן מזג אוויר עדכני כמעט לכל מקום בעולם, בחינם, ובלי הרשמה ובלי מפתח (כל עוד השימוש סביר). לפעמים השרת עמוס ומחזיר תשובה שהשירות לא זמין כרגע. לא נורא, מחכים כמה שניות ומנסים שוב.

נכנסתי בדפדפן לכתובת של מזג האוויר בכפר סבא, וקיבלתי… ערימה של טקסט. במבט ראשון זה נראה כמו ג’יבריש.

JSON, או: איך לקרוא את הג’יבריש הזה

הג’יבריש הזה נקרא JSON (מבטאים “ג’ייסון”), וזה הפורמט שבו כמעט כל ה-APIs מחזירים היום מידע. טיפ ראשון: בכרום יש אפשרות Pretty print. תסמנו אותה וה-JSON יוצג מסודר, עם רווחים ושורות, הרבה יותר קריא.

כמה כללים, ואחריהם זה כבר לא נראה מפחיד:

• שמות השדות תמיד בתוך מרכאות, למשל "name".
• ערכי טקסט (String) גם הם בתוך מרכאות כפולות.
• מספרים נכתבים כמו שהם, שלמים או עשרוניים, בלי מרכאות.
• פסיק (,) מפריד בין פריט לפריט. חובה.
• רשימה של פריטים (Array) נמצאת בתוך סוגריים מרובעים: [...].
• אובייקט בתוך אובייקט (Nested Object) נפתח בסוגריים מסולסלים: {...}.

בתשובה של Open-Meteo מעניין אותנו האובייקט current, מזג האוויר ברגע זה. ובתוכו שני שדות:

1. temperature_2m - הטמפרטורה במעלות צלזיוס (למשל 25.4).
2. weather_code - קוד מספרי שמתאר את מזג האוויר. למשל, קוד 2 פירושו מעונן חלקית.

מזג אוויר בכרטיס הלקוח, עם Claude Code

עכשיו כשאנחנו יודעים אילו שדות צריך, עוברים ל-Claude Code בתיקיית CRM ומבקשים ממנו:

1. להוסיף לחלון הקופץ של הלקוח את מזג האוויר הנוכחי בכפר סבא.
2. להשתמש בכתובת ה-API המדויקת של Open-Meteo.
3. להציג את הטמפרטורה ואת התיאור המילולי לפי weather_code.
4. לעשות deploy בסוף.

אחרי כמה דקות מרעננים את האתר ב-Cloudflare (F5, ואם זה לא מתעדכן אז Shift+F5). לוחצים על כרטיס לקוח, נגיד Olivia, ומופיע: “Kfar Saba now 25°C, מעונן חלקית”. מזג אוויר אמיתי, עכשיו, בתוך ה-CRM.

כמה מושגים: REST API, Endpoint ומבנה הכתובת

שני מושגים שתשמעו הרבה:

• REST API - סוג של API שבו שולחים בקשה לכתובת URL ומקבלים תשובה, בדרך כלל ב-JSON. בדיוק מה שעשינו עכשיו.
• Endpoint (נקודת קצה) - כתובת ספציפית בתוך ה-API, שמיועדת לפעולה מסוימת. למשל, /v1/forecast מחזיר מזג אוויר נוכחי ותחזית, ולנתוני עבר יש Endpoint אחר.

ואיך בנויה הכתובת עצמה? בסרטון הדגמתי את זה בכלי אונליין לבדיקת APIs (ReqBin), אבל החוקים פשוטים:

• סימן שאלה (?) מופיע פעם אחת בלבד, מיד אחרי ה-Endpoint. ממנו מתחילים הפרמטרים (Query Parameters).
• כל פרמטר כתוב בצורה שם=ערך, למשל latitude=32.175.
• אמפרסנד (&) מפריד בין פרמטר לפרמטר, למשל &longitude=34.9¤t=....

ברגע שמבינים את זה, אפשר לקרוא כמעט כל כתובת API ולהבין מה היא מבקשת.

לקוחות מערים שונות: API בשני שלבים

בעולם האמיתי לא כל הלקוחות גרים בכפר סבא. אז צריך לזהות את המיקום לפי העיר של כל לקוח. הבעיה: Open-Meteo לא מכיר שמות של ערים. הוא עובד עם קואורדינטות, קו רוחב וקו אורך (latitude ו-longitude).

הפתרון הוא לעבוד בשני שלבים:

1. Geocoding: פונים לשירות ה-Geocoding של Open-Meteo ומעבירים לו את שם העיר בפרמטר name (למשל name=Kfar Saba).
2. הוא מחזיר JSON עם הקואורדינטות של העיר.
3. עם הקואורדינטות האלה עושים קריאה שנייה, ל-Endpoint של התחזית (forecast), ומקבלים את מזג האוויר בעיר של הלקוח.

ב-Claude Code מבקשים: להוסיף שדה עיר במסך הלקוחות, לפנות עם העיר ל-Geocoding, ואם חזרה תשובה תקינה, לקרוא ל-Forecast עם הקואורדינטות. וחשוב לבקש גם טיפול בשגיאות ובמקרי קצה (מה קורה אם העיר לא נמצאה?). ובסוף, כמובן, deploy.

בדקתי: הכנסתי “הוד השרון” וקיבלתי 25 מעלות. שיניתי ל"תל אביב" וקיבלתי 24. עובד.

בדיקות, באגים והחלטות מוצר

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

1. כששיניתי את העיר (נגיד לירושלים), מזג האוויר לא התעדכן עד שרעננתי את הדף.
2. כשהשארתי את שדה העיר ריק, המערכת הציגה את המיקום הקודם.

ומכאן אחד הדברים הכי חשובים בקורס כולו. למדנו שבעבודה עם AI חייבים לבדוק בעצמכם (QA). Claude לא יתפוס כל באג לבד. אתם אלה שצריכים למצוא את מקרי הקצה, לבקש מקלוד לתקן אותם, ולקבל החלטות מוצר: האם העיר תהיה שדה טקסט חופשי או רשימה סגורה? מה מציגים כשאין מידע? את ההחלטות האלה אף אחד לא יקבל בשבילכם.