רוב האפליקציות נכתבות באמצעות SDK של לקוח, או אולי כתובת URL של API. כתובות ה-URL של ה-API ושל ה-SDK של הלקוח קשורות לגרסה ספציפית של Looker API. האפליקציה תמשיך לפעול גם כש-Looker יבצע שינויים בגרסאות חדשות של ה-API. השינויים בגרסאות אחרות של API לא ישפיעו על האפליקציה שלכם עד שתבחרו לשדרג את ה-Client SDK (או לשנות את כתובת ה-URL של ה-API) כדי להשתמש בגרסה החדשה של Looker API.
איך Looker מבצע שינויים ב-API
ארכיטקטורת Looker API נועדה לספק יציבות לנקודות הקצה של Looker API, ולכן גם יציבות לאפליקציות שלכם.
כשאנחנו מוסיפים עוד תכונות ויכולות ל-Looker, אנחנו גם מעדכנים את Looker API בארכיטקטורת REST כדי לגשת לתכונות החדשות האלה או לנהל אותן. בכל גרסת Looker, אנחנו מוסיפים פונקציות, פרמטרים ומאפיינים חדשים של סוג התגובה לגרסה הנוכחית של Looker API. ברוב המקרים, תוספות ל-API הן לא שינויים שגורמים לשבירת תאימות, ולכן אנחנו יכולים לשמור את הגרסה הקיימת של ה-API בלי להשפיע על קוד האפליקציה הקיים שמבוסס על ה-API. יכול להיות שקוד האפליקציה הקיים לא מודע לפונקציות, לפרמטרים או לתכונות חדשות שמופיעים בגרסאות הבאות של Looker.
אם נבצע שינויים ב-API שיגרמו לכשל בקוד אפליקציה קיים, נכלול את השינויים האלה בגרסה חדשה של ה-API. המשמעות היא שגרסת ה-API הישנה תמשיך לפעול כמו קודם, וגרסת API חדשה תפעל לצדה עם השינויים והעדכונים. יכולות להיות כמה גרסאות API שפועלות זו לצד זו במופע Looker יחיד, כך שאתם יכולים לבחור מתי לשדרג לגרסת ה-API החדשה. הקוד הקיים שנבנה כדי לקרוא לנקודת הקצה הישנה ימשיך לקרוא לנקודת הקצה הישנה. בקוד חדש צריך להפעיל את הגרסה החדשה של נקודת הקצה ברמת גרסת ה-API העדכנית ביותר.
יוצא דופן אחד הוא בעיות אבטחה קריטיות. אם נגלה בעיית אבטחה קריטית שקשורה לחלק מסוים בממשק ה-API, נעשה כל מה שצריך כדי לפתור את בעיית האבטחה הזו בהקדם האפשרי, כולל השבתת הפונקציונליות הפגיעה עד שיהיה פתרון מתאים.
אם אנחנו צריכים להוציא משימוש תכונה, פונקציה או נכס כדי לפנות מקום להטמעה או לפתרון טובים יותר, בדרך כלל אנחנו משאירים את ה-API הנוכחי כמו שהוא, אבל מסמנים את נקודות הקצה המשויכות של ה-API כ'פריטים שהוצאו משימוש' כדי לציין שצריך להפסיק להשתמש בנקודת הקצה בקוד האפליקציה.
שינויים שוברים ותוספים ב-API
שינוי שעלול לשבור את התאימות לאחור הוא שינוי שמוחק או משנה את השם של ארטיפקט קיים של נקודת קצה ב-API. למשל:
- שינוי או מחיקה של שם או סוג של פרמטר
- הוספת פרמטר חדש שנדרש
- שינוי כתובת ה-URL הבסיסית
- שינוי או מחיקה של מאפיין קיים בתגובה
לעומת זאת, שינוי תוספתי יכול להתבצע בנקודות קצה יציבות. לדוגמה:
- פרמטרים חדשים ואופציונליים
- מאפיינים חדשים בתגובות (אנחנו לא רואים בזה שינוי שובר תאימות כי אנחנו מניחים שהקוד שלכם יתעלם ממאפיינים לא מוכרים בתגובות, וזו פרקטיקה נפוצה בקהילת API בארכיטקטורת REST)
אם נקודת קצה יציבה של Looker API צריכה שינוי משמעותי כדי להתקדם עם ארכיטקטורה או פונקציונליות חדשות, השינוי בדרך כלל מתווסף לנקודת קצה חדשה ונכלל בגרסה חדשה של API, כך שנקודת הקצה הקיימת של API נשארת ללא שינוי.
דגלים לנקודות קצה ל-API
רוב נקודות הקצה של ה-API נחשבות יציבות, כלומר לא צפויים בהן שינויים. Looker לא יפרסם שינויים שעלולים לשבור את התאימות לנקודות קצה יציבות, אלא במקרים קיצוניים, כמו תיקון בעיית אבטחה.
יכול להיות שנקודות קצה אחרות של API יסומנו כבטא או כהוצאו משימוש:
- נקודות קצה בגרסת בטא נמצאות בפיתוח פעיל ועשויות להשתנות בעתיד. הם לא מוגנים מפני שינויים שעלולים לשבור את התאימות. כשמשתמשים בנקודות קצה בגרסת בטא, כדאי לשקול אם שינוי ב-Looker API ישבש במיוחד את האפליקציה או את מחזור הפיתוח. אם אתם מתכננים להשתמש בנקודת קצה בגרסת בטא, מומלץ לקרוא את הערות הגרסה של Looker כדי להתעדכן בשינויים.
- נקודות קצה שהוצאו משימוש הן נקודות קצה שעדיין נתמכות ואפשר להשתמש בהן כרגע, אבל הן יימחקו בגרסה עתידית. צריך לעדכן קוד ישן שמשתמש בנקודת קצה שהוצאה משימוש כדי להפסיק את השימוש בנקודת הקצה שהוצאה משימוש. כשגרסה עתידית של Looker תסיר את התמיכה בנקודת הקצה הזו, כל קוד שעדיין משתמש בה יישבר. ברוב המקרים, נקודת קצה שהוצאה משימוש תוחלף בפונקציונליות משופרת. אם גיליתם שהאפליקציה שלכם משתמשת בפונקציה או במאפיין שיצאו משימוש, מומלץ לבצע רפקטורינג בקוד כדי להחליף את הרכיב שיצא משימוש בהקדם האפשרי.
נקודות קצה בגרסת בטא ונקודות קצה שהוצאו משימוש מסומנות ככאלה ב-API Explorer וב-4.0 API Reference. נקודות קצה שלא מסומנות נחשבות ליציבות.
סוגים של קריאות ל-API
הסוגים של קריאות ל-API שמוגדרות כקריאות ל-API של שאילתות הם:
- שיחות שנדרשות לצינורות אוטומטיים של שאילתות
- שיחות שמקבלות נתונים ממסד הנתונים של הלקוח
- קריאות שמריצות שאילתות SQL או ששולפות תוצאות לתוכן
דוגמאות:
הסוגים של קריאות ל-API שמוגדרות כקריאות ל-Admin API הם:
- קריאות שנדרשות כדי ליצור אפליקציות, לשלוט בתוכן בכמה מופעים ולבצע משימות ניהול
- קריאות ששולטות במכונה של Looker (Google Cloud Core)
- שיחות שמבצעות ניהול תוכן, ניהול הרשאות ומשתמשים, ניהול מופעים או שליפת תוכן מתיקיות
לדוגמה:
מעבר לגרסה חדשה של API
כשמשדרגים את כתובת ה-URL של ה-API או של ה-SDK של הלקוח לגרסה חדשה של ה-API, צריך לבדוק את קוד האפליקציה כדי לראות אם יש בו הסתמכות על משהו שהשתנה בגרסה החדשה של ה-API. חשוב לבצע את הפעולות הבאות:
- מחפשים בקוד האפליקציה את הפונקציה, הערך ושמות הנכסים המעודכנים.
- מוודאים שקוד האפליקציה תומך בשינויים בסוגים (למשל, מ-integer למחרוזת).
- בודקים את הקוד (ראו את הקטע בנושא בדיקת הקוד).
בדיקת הקוד
בשפות מסוימות, אפשר לגלות שינויים שעלולים לשבור את התאימות ב-API משך זמן של תהליך build כשגיאות קומפילציה:
- אם האפליקציה שלכם כתובה בשפה מהודרת עם הקלדה חזקה, שינויים מבניים בסוגי פרמטרים או תגובות בגרסה חדשה של API שלא תואמים לקוד הקיים שלכם אמורים להיות ברורים בזכות בדיקת סוגי ההידור והודעות השגיאה של הקומפיילר.
- אם האפליקציה שלכם כתובה בשפה דינמית עם טיפוסי נתונים חלשים (כמו JavaScript, Ruby ו-Python), יכול להיות שיהיה קשה יותר לאתר את החלקים באפליקציה שיושפעו משינויים שעלולים לשבור תאימות בגרסה חדשה של ה-API. בשפות כאלה יכול להיות שיהיה צורך בבדיקות יחידה בזמן ריצה כדי למצוא בעיות שקשורות לשינויים בסוגים.
בכל המקרים, השיטה המומלצת היא להשתמש בבדיקות יחידה שמפעילות את קוד האפליקציה, כולל קריאות ל-Looker API (לא קריאות מדומה).