מה זה API?

API - עבודה מחוץ לממשק

תחשבו על זה שיש לנו תוכנה כלשהי, למשל אקסל.

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

אבל יש דרך אחרת לגשת לאקסל שלנו, וזה נקרא API - Application Programming Interface (ממשק תכנות יישומים).

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

למה זה חשוב

כמו שכתבנו קודם - בעזרת API, נוכל לדבר עם התוכנה בלי להיכנס לאפליקציה באופן ישיר, וזה יכול לעזור לנו במגוון תהליכים שנרצה לעשות בתוכנה שלנו (בקוד או בכלי נו-קוד כמו Make/n8n/Zapier וכלים דומים) בלי לפתוח תוכנות אחרות - אבל עדיין לקבל מהם את המידע.

למשל, אם משתמש ישאל אותנו בווצאפ 'מתי התור שלי?' נוכל לבצע בקשת API, לבדוק באקסל שלנו ולזהות מתי התור של הלקוח, ובעזרת בקשת API לווצאפ - להחזיר לו את התשובה המדויקת.

כל זה יתבצע מאחורי הקלעים, בלי שנכנסנו לווצאפ ובלי שנכנסנו לאקסל או למערכת ה-CRM וחיפשנו את הלקוח ומתי התור שלו, וזה מתאפשר בזכות ה-API שמאפשר לתוכנות 'לדבר אחת עם השנייה'.

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

איך זה עובד

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

תוכנה שתומכת ב-API (לא כולם כאלה, אבל המון כן) יהיו לה מסמכים מסודרים (API Documentation) שמסבירים למפתח איך להשתמש ב-API של התוכנה ולעבוד עם התוכנה גם כשלא נהיה פיזית על המחשב.

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

ממה בקשת API מורכבת

כתובת

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

בדרך כלל מבנה הקישור מורכב מ:

• Base URL - הכתובת הבסיסית של הדומיין שאליו יתבצעו כל קריאות ה-API.
• הנתיב הספציפי - נתיב ייחודי לבקשה הספציפית שנרצה לעשות.

לפעמים נראה גם v1 שמעיד על גרסה של ה-API.

סוג הבקשה

ישנם מספר סוגי קריאות API לפי הפעולה שה-API מבצע ושיקולים נוספים של המתכנתים. העיקריים שבהם:

• POST - משמש לביצוע פעולות יצירה כמו יצירת שורה חדשה, יצירת לקוח חדש או שליחת הודעה.
• GET - משמש לקבלת מידע ונתונים כמו קבלת פרטי השורה או קבלת פרטי הלקוח.
• PUT - משמש לעריכת מידע קיים כמו שינוי תוכן השורה או עדכון פרטי לקוח.
• DELETE - משמש למחיקת נתונים כמו מחיקת שורה או מחיקת לקוח.

לפעמים מפתחים מעדיפים להשתמש בסוג POST גם כדי לקבל מידע ויכולות להיות סיבות שונות לזה. למשל: העדפה להעביר מידע בגוף הבקשה ולא ב-URL (לרוב בקשות GET מתבצעות ללא גוף) כדי לשמור על תוכן המידע או כשיש הרבה מידע (בקשות POST יכולות להכיל יותר מידע).

כותרות

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

אימות

רוב השירותים ידרשו מאיתנו אימות - זו הדרך לוודא שמי שמבצע את הבקשה זה באמת אנחנו (אותנטיקציה/Authentication), ושמותר לנו לגשת למידע (הרשאה/Authorization).

בדרך כלל האימות ייעשה באמצעות טוקן (Token) או מפתח API (API Key) - מחרוזת סודית שמזהה אותנו, שנקבל מהשירות ואותו נצרף לבקשה. בלי האימות הזה השירות פשוט ידחה אותנו ויחזיר שגיאה (לרוב 401 - "מי אתה? אין לך הרשאה").

חשוב לשמור על הטוקן בסוד - מי שמשיג אותו יכול לבצע פעולות בשמנו!

גוף הבקשה

יכיל את המידע שאנחנו רוצים לעדכן. למשל פרטי הליד החדש או עדכון פרטי הליד. לרוב יופיע בבקשות מסוג POST/PUT. בבקשות מסוג GET כשנדרש מידע, לרוב הוא יועבר ב-URL עצמו באמצעות QS (Query String) או Path Parameters.

המידע נשלח בדרך כלל בפורמט שנקרא JSON - דרך מוסכמת לכתוב נתונים בצורה מסודרת (זוגות של "שם" ו"ערך") שגם אנחנו וגם השירות יודעים לקרוא.

תשובה

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

התשובה מורכבת מכמה פרמטרים עיקריים:

• קוד - מספר קצר שמסכם אם הבקשה הצליחה או נכשלה, בלי הפירוט המלא. למשל 200 מסמל הצלחה, 400 כישלון בצורת כתיבת הבקשה, 500 תקלה מצד השרת.
• תשובה קצרה - בדרך כלל יתלווו לקוד מילים קצרות וממוקדות כמו Accepted או ok ובמקרה של כישלון Not Found.
• גוף התשובה - דומה לגוף הבקשה שראינו קודם - הפרטים המלאים עם המידע על ההצלחה או הכישלון של הבקשה.

הקודים שציינתי קודם הם 'משפחות' - יכול להיות גם 201 או 404 ו-503, לכל מספר יש שגיאה ספציפית יותר לפי סטנדרטים של התעשייה ושל השירות הספציפי.

דוגמא

אחרי שהבנו את הרעיון, בואו נראה דוגמא. לצורך ההבנה אני אשתמש בקריאה של GREEN-API שאני הנציג שלהם בארץ והמבנה של הבקשות מאוד ברור ופשוט להבנה.

שליחת הודעת טקסט

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

{{apiUrl}}/waInstance{{idInstance}}/sendMessage/{{apiTokenInstance}}

סמוך ל-URL גרין ציינו לנו שהבקשה היא מסוג POST, לא נדרשים Headers לביצוע הבקשה הזאת.

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

ניקח את הדוגמאות הפשוטות עם שדות החובה בלבד:

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

לסיכום

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

זכרו: כל API חדש הוא בסך הכל וריאציה על אותו רעיון!

---

שאלות? צרו קשר ב-WhatsApp.