Exploring APIs – מעבדת היכרות עם שירותי רשת

שלב 1 – התקנת Postman

Postman הוא כלי חיוני באוטומציה ובניית סוכנים, המאפשר לשלוח בקשות HTTP ולבדוק ממשקי API בצורה נוחה וידנית, לפני שמשלבים אותם באוטומציה.

• אם עדיין לא הורדתם והתקנתם את תוכנת Postman – עשו זאת כעת לפי ההוראות המפורטות כאן.

שלב 2 – יצירת API Key לשירות מזג האויר OpenWeatherMap

נשתמש ב-API של OpenWeatherMap כדי לאפשר ל-Agent שלנו לשלוף מידע עדכני על מזג אוויר.

• אם עדיין אין לכם מפתח גישה (API Key) לשירות מזג האויר OpenWeatherMap – עשו זאת כעת לפי ההוראות המפורטות כאן.

שלב 3 – יצירת API Key למנוע החיפוש Tavily

Tavily הוא מנוע חיפוש מבוסס AI, המותאם במיוחד עבור Large Language Models (LLMs) ו-Agents. הוא מאפשר חיפוש מידע עדכני באינטרנט בצורה יעילה.

• אם עדיין אין לכם מפתח גישה (API Key) למנוע החיפוש Tavily – עשו זאת כעת לפי ההוראות המפורטות כאן.

שלב 4 – בקשת API לשירות OpenWeatherMap

בתרגול זה נתנסה בשירות API פופולרי נוסף, OpenWeatherMap, המספק נתוני מזג אוויר. שירות זה פועל מעט אחרת (לרוב בשיטת GET עם פרמטרים ב-URL), וזו הזדמנות טובה לתרגל סוג נוסף של קריאה.
 

1. איתור Endpoint ופרמטרים (קריאת דוקומנטציה):
    
   • גשו לאתר הרשמי של שירות OpenWeatherMap וחפשו את הקישור לדוקומנטציה של ה –"API".
     לא מצאתם? נסו כאן: https://openweathermap.org/api.
   • חפשו את התיעוד עבור השירות "Current Weather Data" (נתוני מזג אוויר נוכחיים) ולחצו על כפתור API Doc.
      
     

     

   • עיינו בדוקומנטציה וחפשו את השירות request by city name. שירות זה מחזיר את מזג האויר הנוכחי לפי שם של עיר בעולם.
     תחת הכותרת תמצאו הסברים מפורטים על אופן שליחת הבקשה לשירות זה:
      
     • (שימו לב – מפורטים רק שורות כתובת, ללא כותרות או גוף. זה מעיף על בקשת GET פשוטה) מבנים שונים של קריאה
     • הסבר על הפרמטרים השונים בשורת הכתובת
     • דוגמאות
   • חפשו בדוקומנטציה את כתובת ה-URL הבסיסית (Base URL), היא כנראה תיראה בדומה ל: https://api.openweathermap.org/data/2.5/weather
   • בדקו בדוקומנטציה אילו פרמטרים (Query Parameters) חובה לשלוח: לרוב אלו יהיו שם עיר (פרמטר q) ומפתח API (פרמטר appid).

    
   

   

2. שליחת בקשת GET ב-Postman:
    
   • פתחו לשונית חדשה ב-Postman וודאו שהיא מוגדרת כבקשת GET (זו ברירת המחדל).
   • הדביקו את כתובת ה-URL שאיתרתם בשדה הכתובת. אם לא מצאתם בדוקומנטציה, השתמשו בכתובת הזאת:

     
     https://api.openweathermap.org/data/2.5/weather
     

   • עברו ללשונית "Params" (נמצאת מתחת לשורת ה-URL). זו הדרך הקלה להוסיף Query Parameters לבקשת GET.
      
     

     

   • בשדה KEY הוסיפו q ובשדה VALUE הוסיפו שם עיר, למשל Jerusalem.
   • בשורה חדשה ב-Params, הוסיפו KEY בשם appid וב-VALUE הדביקו את מפתח ה-API שלכם.
   • בשורה חדשה נוספת (אופציונלי, מומלץ), הוסיפו KEY בשם units ו-VALUE בשם metric (כדי לקבל מעלות בצלזיוס).
   • שימו לב כיצד הפרמטרים שהוספתם נוספו אוטומטית לכתובת ה-URL הראשית (עם סימן ? ו-&).
      
     

     

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

     
     https://api.openweathermap.org/data/2.5/weather?q=Jerusalem&appid=d599cfa256007c68869d035b853416c9
     

   • לחצו Send.
3. ניתוח התגובה (Response):
    
   • אם הכל תקין, תקבלו בחזרה אובייקט JSON עם נתוני מזג האוויר.
   • נסו לאתר את האובייקט main ואת השדה temp בתוכו – זו הטמפרטורה הנוכחית.
   • נסו לאתר את המערך weather ואת השדה description בתוכו – זהו תיאור מילולי של מזג האוויר.
   • שנו את שם העיר ב-Params (למשל ל-London או New York) ושלחו שוב כדי לראות נתונים של עיר אחרת.

שלב 5 – סקירת הדוקומנטציה של מנוע החיפוש Tavily

לאחר שלמדנו לשלוח בקשת GET פשוטה, כעת נתנסה בבקשה קצת יותר מורכבת, הכוללת גם כותרות (Headers) וגוף (Body).

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

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

1. סקירת הדוקומנטציה של נקודות הקצה (Endpoints):
    
   • עברו לאתר הדוקומנטציה של Tavily (חפשו "Tavily API Docs" בגוגל או היכנסו דרך הקישור באתר).
   • במידה וגעתם לעמוד Welcome של הדוקומנטציה (כותרת Explore our docs) – חפשו קישור ל API Reference והקליקו עליו.
      
     

     

   • עדיין לא מצאתם? גשו לקישור הזה:
     https://docs.tavily.com/documentation/api-reference/endpoint/search
   • הקדישו מספר דקות לבחון את נקודות הקצה (הפונקציות השונות) בפאנל הניווט, כגון Search, Extract, Crawl וכו'.
2. בחינת פונקציית Search:
    
   • בחרו בפונקציית Search ושימו לב למבנה הוראות השימוש ב-API זה.
   • מימין, תוכלו לראות מסגרת של דוגמת בקשה.
      
     

     

3. מעבר לדוגמת cURL:
   • כיוון שאנו עובדים עם Postman ולא כותבים קוד פייתון כרגע, נחפש דוגמה גנרית יותר.
   • לחצו על הלחצן שבו כתוב Python (או שפת תכנות אחרת) ובחרו באפשרות cURL.
   • דוגמת ה-cURL מתארת בדיוק את החלקים השונים ב-API Request שנבצע ב-Postman. שימו לב למבנה שלה:
      
     

     

   • בדוגמה זו ניתן לראות את ה-URL המלא, את הכותרות (Headers) ואת מבנה גוף הקריאה (Body) בפורמט JSON.
   • שימו לב: מבנה ה cURL שמופיע כאן, אינה בקשת HTTP ״נקיה״, אבל מתוך המבנה הזה ניתן להעתיק את ערכי שורת הכתובת, הכותרות וגוף הבקשה. לדוגמא:
      
     1. בשורת הראשונה ניתן לראות את המילה POST לאחר הפרמטר --request. זוהי המתודה של הבקשה.
     2. בשורת השניה ניתן לראות את הכתובת המדויקת של שירות החיפוש
        https://api.tavily.com/search לאחר הפרמטר --url.
     3. בשורת השלישית והרביעית אנו רואים ערכים שונים של כותרות. לדוגמא:
        Authorization: Bearer <token> לאחר הפרמטר --header שבשורה השלישית.
     4. ולבסוף, ניתן לראות את גוף הבקשה (Body) שמופיע מיד לאחר הפרמטר --data.
         
        שימו לב – במקרה הזה, גוף הבקשה הוא בפורמט JSON, ונמצא בתוך גרשיים. כשנעתיק אותו ל Postman, נשתמש רק במבנה ה JSON עצמו, שבתוך הגרשיים הללו.

שלב 6 – שליחת בקשת API למנוע החיפוש Tavily

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

1. יצירת בקשת POST חדשה:
    
   • ב-Postman, פתחו לשונית חדשה (לחצו על +).
      
     

     

   • בצד שמאל של שורת הכתובת, שנו את מתודת הבקשה ל-POST.
      
     

     

   • בשדה ה-URL, הדביקו את הכתובת: https://api.tavily.com/search כפי שראינו במבנה ב cURL בפרק הקודם.
2. הגדרת הכותרות Headers:
    
   • עברו ללשונית Headers (מתחת לשורת הכתובת).
   • בתחתית רשימת הכותרות, בשורה חדשה, בעמודת KEY, רשמו: Content-Type
   • בעמודת VALUE באותה שורה, רשמו: application/json
      
     

     

   • בשורה חדשה נוספת, בעמודת KEY, רשמו: Authorization
   • בעמודת VALUE, רשמו: Bearer <YOUR_API_KEY>
   • שימו לב: החליפו את המקטע <YOUR_API_KEY> (כולל הסוגריים המשולשים) במפתח המלא שהעתקתם מאתר Tavily.
3. הגדרת גוף הבקשה (Body):
    
   • עברו ללשונית Body.
   • סמנו את האפשרות raw.
   • בסרגל הקטן שמופיע מימין, לחצו על הטקסט (כנראה Text) ובחרו JSON.
   • בתיבת הטקסט הגדולה, הדביקו את ה-JSON הבא:

     
     {
         "query": "Who is Leo Messi?"
     }
     

      
     

     

4. שליחה וניתוח התגובה:
   • לחצו על כפתור Send.
   • התבוננו בתגובה (Response) שמתקבלת בחלק התחתון של המסך.
   • נסו להסביר מהם השדות החשובים שקיבלתם, למשל: results, snippets, query.
   • נסו לשנות את השאילתה ב-Body לשאלות שונות (בעברית, באנגלית) ולשלוח שוב. התנסו גם בפרמטרים נוספים שראיתם בדוקומנטציה.

תרגול עצמאי

עכשיו – אתגר: בחרו שירות API נוסף (לדוגמא Serp API – שירות לחיפוש תוצאות Google, או כל שירות אחר שמעניין אתכם).

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