שימוש נכון ב-API: מטמון, Webhook ומגבלות קצב
Premiumשילוב שפונה ל-Omniscol מדי דקה כדי לבדוק אם נתונים השתנו מקבל, ברוב המקרים, את אותה תשובה כמו בקריאה הקודמת. הוא צורך את המכסה שלו שלא לצורך ומעמיס על השרת בלי לקבל מידע חדש.
דף זה מציג את המנגנונים שמונעים קריאות מיותרות כאלה ואת מגבלות הקצב החלות על ה-API.
להימנע משליפה חוזרת של נתונים שלא השתנו
רוב תשובות הקריאה של ה-API כוללות כותרת ETag, המזהה גרסה של התשובה. שמרו
מזהה זה יחד עם הנתונים שהתקבלו, ושלחו אותו בקריאה הבאה בכותרת
If-None-Match:
curl -i -G "https://votre-etablissement.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
אם הנתונים לא השתנו, Omniscol משיב 304 Not Modified, ללא גוף תשובה. אז ניתן
להשתמש שוב בנתונים השמורים במטמון. אחרת מתקבלת תשובה מלאה 200 OK, יחד עם
ETag חדש.
ה-ETag הוא ערך אטום: שמרו אותו ושלחו אותו בדיוק כפי שהתקבל, כולל המרכאות
והקידומת W/, בלי לנסות לבנות אותו או לפענח אותו. הוא שייך לבקשה שהפיקה אותו
ולגישה שבה נעשה שימוש: אין להשתמש בו עבור כתובת URL אחרת או עם טוקן אחר.
הכותרת Cache-Control: private, no-cache מציינת שניתן לשמור את התשובה במטמון
פרטי, אך יש לאמת אותה מחדש מול Omniscol לפני שימוש חוזר בה. זהו בדיוק תפקידה
של הכותרת If-None-Match.
חלק מהתשובות אינן כוללות ETag, בעיקר כשהן תלויות בתאריך היום ועשויות להשתנות גם בלי שינוי בנתוני החשבון. תשובות אלה יש לשלוף מחדש בכל קריאה.
לאחר פריסה של גרסה חדשה של Omniscol, ה-ETag מתחדשים גם אם הנתונים לא השתנו.
הקריאה הראשונה מקבלת אז תשובה 200, ובקריאות הבאות ניתן שוב ליהנות מתשובות
304.
תשובת ה-304 גם מפחיתה את העיבוד בצד השרת. ברוב המקרים, כשלא השתנה אף נתון
בחשבון מאז הקריאה האחרונה, Omniscol יכול להשיב בלי לקרוא מחדש את הנתונים
הרלוונטיים, ותשובת 304 כזו אינה נספרת במכסה של מפתח ה-API שלכם. תשובת 304
שהתקבלה לאחר קריאה מחדש של הנתונים נספרת כתשובה רגילה.
אימות חוזר סדיר נשאר אפוא זול כשהנתונים לא השתנו. עם זאת, הוא כפוף למגבלה הכללית לפי כתובת IP.
לשמור תשובות במטמון
אם כמה משתמשים או כמה מסכים באפליקציה שלכם צופים באותם נתונים, אין טעם לפנות ל-Omniscol עבור כל אחד מהם.
שמרו את התשובות ואת ה-ETag שלהן במטמון אפליקטיבי שבשליטתכם, למשל Redis,
Memcached או טבלה במסד נתונים. האפליקציה שלכם יכולה אז לספק את הנתונים
מהמטמון, והוא מאמת אותם מחדש מול Omniscol באמצעות If-None-Match, במרווחי
זמן קבועים או כש-Webhook מדווח על שינוי.
מפתח המטמון צריך לכלול את כתובת ה-URL המלאה, את טוקן האימות שבו נעשה שימוש
ואם אתם משתמשים בהם, גם את גוף בקשת ה-GET ואת הכותרות שמשנות את התשובה,
כמו Accept-Language. שני טוקנים בעלי הרשאות שונות עשויים לתת גישה לנתונים
שונים: תשובה שהתקבלה עם אחד מהם אסור שתוגש למשתמש שהרשאותיו אינן מאפשרות לו
גישה אליה.
שמרו גם את גוף כל תשובה יחד עם ה-ETag שלה. בלי הנתונים המתאימים, תשובת 304
אינה מאפשרת לשחזר את התוצאה הצפויה.
המטמון האפליקטיבי הזה שונה ממטמון HTTP משותף: ההנחיה Cache-Control: private
אוסרת על מטמון משותף לאחסן את התשובות.
לקבל התראות במקום לבדוק בתדירות קבועה
במקום לבדוק מדי פעם אם נתונים השתנו, ניתן לבקש מ-Omniscol להתריע לאפליקציה שלכם כשמתרחש שינוי.
מנגנון זה מבוסס על Webhook, שניתן להגדיר במסך ההתאמה האישית של ה-API (ראו את הדף התאמה אישית של API). Webhook יכול לעקוב אחר נקודת קצה מסוימת או אחר אירוע מקובץ שכולל כמה שינויים, כמו שינוי במערכת שעות.
לבטל את המטמון עם קבלת Webhook
השימוש הפשוט ביותר הוא להתייחס ל-Webhook כאל אות לביטול תוקף.
כשמגיעה התראה, האפליקציה שלכם מסמנת את הנתונים הרלוונטיים כלא עדכניים ומאמתת אותם מחדש מול Omniscol. אין צורך לפרש את תוכן השינוי: ה-Webhook מציין רק שנדרשת בדיקה חדשה.
דרך פעולה זו משתלבת באופן טבעי עם המטמון שתואר לעיל.
לסנכרן שיעורים באמצעות הפרשים
אם אתם מחזיקים עותק מסונכרן של השיעורים, האפשרות עם נתונים באירוע שינוי מערכת השעות מאפשרת לקבל הפרשים שכוללים את השיעורים שנוספו, שונו ונמחקו.
האפליקציה שלכם יכולה אז להחיל רק את השינויים האלה, בלי לשלוף מחדש את מערכת השעות כולה.
להבטיח את קבלת ההתראות
Omniscol מבצע ניסיון שליחה יחיד לכל Webhook. הוא ממתין ארבע שניות לכל היותר, אינו מנסה שוב במקרה של כישלון ורושם את הכישלון ביומנים שלו.
לכן השרת שלכם צריך לאשר קבלה במהירות, בתשובת 200 OK או 202 Accepted,
ולבצע את העיבוד הנדרש באופן אסינכרוני.
שמרו גם אימות חוזר סדיר כמנגנון השלמה. אם השרת שלכם לא היה זמין בעת שליחת
Webhook, בדיקה זו תאפשר לזהות את השינויים שהוחמצו. הודות לתשובות 304, היא
נשארת זולה כשהנתונים מעודכנים.
לאבטח Webhook
כדי לוודא שהתראה אכן מגיעה מ-Omniscol, הגדירו כותרת HTTP מותאמת אישית שכוללת סוד המוכר רק לאפליקציה שלכם ול-Omniscol. השרת שלכם צריך לדחות קריאות שאינן מציגות את הערך הצפוי.
שתי כותרות נוספות מספקות מידע על הקשר ההתראה:
X-Schoolמזהה את חשבון Omniscol הנוגע בדבר;X-OS-authכוללת את טוקן האימות של המשתמש שביצע את השינוי.
הטוקן המועבר ב-X-OS-auth הוא סודי. אל תרשמו אותו ביומנים שלכם, אל תעבירו
אותו לשירותים אחרים והגבילו בקפדנות את הגישה אליו.
לבקש רק את הנתונים הנחוצים
תשובה עם פחות נתונים מהירה בדרך כלל יותר להפקה, להעברה ולשמירה במטמון.
לגבי שיעורים, הגבילו את התקופה המבוקשת וסננו את התוצאות לפי הישויות שמעניינות אתכם (ראו את הדף API השיעורים).
לגבי חיפושים, נקודת הקצה search/query מציעה מסננים, הקרנת שדות ועימוד (ראו
את הדף שאילתות מתקדמות).
כדי לעדכן מספר רב של פריטים מאותו סוג (כיתות, כיתות לימוד, מקצועות וכן הלאה), העדיפו נקודות קצה שמאפשרות לשלוח אוסף שלם בבקשה אחת, כשהן מופיעות בתיעוד OpenAPI, על פני ריבוי קריאות בודדות.
לעמוד במגבלות הקצב
שתי מגבלות קצב חלות על הקריאות ל-API. כשמגיעים למגבלה, Omniscol משיב
429 Too Many Requests, עם כותרת Retry-After שמציינת כמה שניות יש להמתין
לפני שליחה חוזרת של הבקשה.
מגבלה לפי כתובת IP
המגבלה הכללית היא 300 בקשות בחלון של 10 שניות, בכל נקודות הקצה של ה-API, כולל MCP ולוחות תצוגה.
סף זה מספיק בדרך כלל לשילוב שתוכנן כראוי. עם זאת, ניתן להגיע אליו בלולאות קריאות ללא השהיה או במספר מופרז של בקשות מקבילות.
מגבלה לפי מפתח API
טוקנים שמקורם באותו מפתח API חולקים שתי מכסות:
- 60 בקשות בדקה;
- 5,000 בקשות ביום.
התשובות עשויות לשאת את הכותרות הבאות, המאפשרות לעקוב אחר הצריכה:
RateLimit-Policyמציינת את המכסות החלות, למשל60;w=60, 5000;w=86400;RateLimit-Limitמציינת את המכסה המתאימה למגבלה הקרובה ביותר להגעה;RateLimit-Remainingמציינת את מספר הבקשות שנותרו במכסה זו;RateLimit-Resetמציינת את מספר השניות עד לחידושה.
כותרות אלה נעדרות בין היתר מתשובות 304 שהתקבלו בלי קריאה מחדש של הנתונים:
היעדרן אינו אומר שהמכסה אזלה.
כשהמכסה אזלה, תשובת ה-429 מציינת את זמן ההמתנה גם בגוף שלה, בשדה
retry_after.
תשובות 304 שהתקבלו בלי קריאה מחדש של הנתונים אינן נספרות במכסות אלה, אך
הן עדיין כפופות למגבלה הכללית לפי כתובת IP.
אם המגבלות האלה מפריעות לשימוש לגיטימי ב-API, פנו אלינו במקום להרבות במפתחות.
לטפל בשגיאות ובניסיונות חוזרים
אחרי תשובת 429
כבדו את זמן ההמתנה שמציינת Retry-After לפני שליחה חוזרת של הבקשה. ניסיון
חוזר מיידי חסר תועלת ועלול להאריך את המצב, בעיקר אם כמה תהליכים באפליקציה
שלכם מנסים שוב בו-זמנית.
אחרי שגיאת שרת או חריגה ממגבלת הזמן
אחרי שגיאת 5xx או חריגה ממגבלת זמן ההמתנה, ניתן לשלוח שוב בקשת קריאה עם
השהיה הולכת וגדלה בין הניסיונות: למשל שנייה, אחריה שתיים, אחריהן ארבע,
עד מספר מרבי של ניסיונות.
בבקשת כתיבה המצב שונה: ייתכן שהשינוי נשמר גם אם התשובה לא הגיעה אליכם מעולם. בדקו את המצב בפועל של הנתונים לפני שליחה חוזרת של הפעולה, כדי להימנע משינויים כפולים.
אחרי תשובת 401
לרוב לא ניתן לפתור תשובת 401 Unauthorized בניסיון חוזר עם אותו טוקן. היא
עשויה לציין, בין היתר, שהטוקן פג, שמפתח ה-API שלו נמחק או פג, או שנקודת
הקצה המבוקשת אינה בין אלה שהוא מתיר.
בדקו את הטוקן ואת ההרשאות המשויכות אליו לפני שליחה חוזרת של הקריאה (ראו את הדף Omniscol API).