איך מחברים API לאתר: בקשה, תשובה, מפתח, ומה עושים כשזה נשבר

חיבור של ממשק כזה לאתר בנוי על 4 פעולות קבועות: פנייה דרך fetch, הגדרת נתונים, קריאת תשובה בפורמט JSON, ובדיקת סטטוס התגובה. כל בקשה מתבססת על כתובת רשת שמקבלת מידע ומחזירה תשובה מובנית. בדפדפנים מודרניים הפונקציה הגלובלית fetch זמינה ישירות באובייקט window ובסביבת worker. היא מחליפה לחלוטין את מנגנון XMLHttpRequest הישן שנשען על callbacks מסורבלים. השימוש במנגנון המובנה הזה בדפדפן עולה 0 שקלים, כי הוא חלק בלתי נפרד מכל מנוע גלישה מודרני.

זה עובד מהר.

שליחת בקשה ראשונה

כדי למשוך מידע מהרשת, קוראים לפונקציה fetch ומעבירים לה כתובת יעד. אפשר להעביר מחרוזת טקסט פשוטה, אובייקט מסוג URL, או מופע של Request. הפונקציה מחזירה Promise שמניב אובייקט Response ברגע שהשרת עונה. כברירת מחדל, הפנייה יוצאת בשיטת GET ללא גוף נתונים. אם אתם צריכים להעביר פרמטרים בתוך קריאת GET, מרכיבים אותם ישירות לתוך הכתובת באמצעות URLSearchParams שמייצר מחרוזת שאילתה תקינה ומסודרת.

הפונקציה fetch לא נכשלת אוטומטית כשהשרת מחזיר שגיאה 404. מבחינת הדפדפן, כל עוד התקבלה תשובת HTTP כלשהי מהשרת, הפעולה הצליחה וההבטחה מתממשת בהצלחה. לכן הקוד שלכם חייב לבדוק את ערך response.ok לפני שנוגעים בתוכן התשובה. אם המאפיין שלילי, זורקים שגיאה עם המספר המדויק של סטטוס התגובה שהתקבל. רק לאחר מכן מפעילים את פונקציית response.json, שפועלת בצורה אסינכרונית כדי לחלץ את גוף הנתונים למבנה שניתן לעבוד איתו.

דוגמת הקוד המדויקת מתוך התיעוד של MDN מדגימה את ארבעת השלבים הבסיסיים הללו:

async function getData() { const url = "https://example.org/products.json"; try { const response = await fetch(url); if (!response.ok) { throw new Error(`Response status: ${response.status}`); } const result = await response.json(); console.log(result); } catch (error) { console.error(error.message); } }

שליחת נתונים ומבנה הבקשה

כשרוצים לשמור נתונים חדשים או לעדכן רשומות, שיטת GET כבר לא תעזור ותצטרכו להגדיר שיטות כמו POST או PUT. במצב כזה מעבירים אובייקט הגדרות כפרמטר שני לפונקציה. האובייקט הזה כולל את המאפיין method ואת המאפיין body שנושא את המידע. גוף הבקשה תומך במגוון סוגים, כגון מחרוזת טקסט רגילה או מבנה מסוג FormData. עבור נתונים מובנים ומורכבים, מעבירים מחרוזת שמייצרים בעזרת הפקודה JSON.stringify ישירות לאפשרות ה-body.

יחד עם גוף הבקשה תצטרכו להגדיר כותרות מתאימות תחת המאפיין headers. הכותרת Content-Type מדווחת לשרת באיזה פורמט המידע נשלח. עבור נתוני ג'ייסון משתמשים בערך application/json, ועבור טפסים רגילים משתמשים בערך application/x-www-form-urlencoded. אפשר להגדיר כותרות כאובייקט רגיל, או ליצור מופע של מחלקת Headers. המחלקה הזו מנקה רווחים מיותרים, ממירה את שמות השדות לאותיות קטנות, וחוסמת שינוי של שדות מסוימים המוגדרים ככותרות אסורות.

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

הזרם נקרא פעם אחת.

מנגנון CORS ומגבלות דפדפן

כשמנסים לפנות לדומיין חיצוני, הדפדפן מפעיל מנגנון הגנה שנקרא Cross-Origin Resource Sharing. מנגנון CORS נשען על כותרות HTTP כדי לקבוע אם לאתר מסוים מותר לטעון משאבים מדומיין אחר. מאז יולי 2015 התקן הזה נתמך ופועל בכל הדפדפנים המרכזיים. שרת מרוחק חייב להחזיר כותרת Access-Control-Allow-Origin שמאשרת את הדומיין שלכם או מכילה כוכבית. ללא כותרת כזו, הדפדפן יחסום לחלוטין את קריאת המידע על ידי הסקריפט.

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

הדפדפן מגדיר בקשה פשוטה ככזו שמשתמשת באחת מתוך 3 שיטות בלבד: GET, HEAD או POST. בבקשות כאלה מותר להשתמש רק בכותרות בסיסיות, וסוג המדיה חייב להיות מוגבל לערכים מוגדרים. אם אתם שולחים נתוני JSON עם כותרת ייעודית, הדפדפן יחייב בדיקה מקדימה לפני ביצוע הפעולה.

אימות נתונים ואבטחת מפתחות

מפתח API הוא מחרוזת סודית שמזהה מי שולח את הבקשה ומאפשרת לשרת להגביל גישה או לחייב בתשלום. פרטי זיהוי נוספים כוללים עוגיות של הדפדפן, תעודות TLS, או שימוש בכותרת Authorization. כברירת מחדל, הדפדפן שולח עוגיות ופרטי זיהוי רק עבור פניות לאותו מקור. כדי לשנות התנהגות זו, תצטרכו להגדיר את מאפיין credentials לערך כמו include או omit בהתאם לדרישות השרת.

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

קוד פתוח בדפדפן גלוי.

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

מקורות

• developer.mozilla.orghttps://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
• developer.mozilla.orghttps://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Client-side_APIs/Introduction
• developer.mozilla.orghttps://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS

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