גישה, מפתחות ופרטיות
מפתחות#
- פרויקט מקבל מפתחות אחרי שהבקשה שלו מאושרת: איך הגישה עובדת. מפתחות נוצרים באזור המפתחים ומוצגים פעם אחת.
- מבנה:
ibk_live_k_<10 תווים>_<43 תווים>(ibk_test_…לבדיקות). החלק שלפני ה-_האחרון הוא קידומת ציבורית שמופיעה באזור המפתחים ובדחיות; השאר סודי. - שלחו את המפתח רק בכותרת:
Authorization: Bearer <מפתח>. מפתח בכתובת הבקשה נדחה (KEY_IN_QUERY), וכדאי להחליף אותו: כתובות נשמרות ביומנים. - שמרו מפתחות בשרתים: לא בדפי אינטרנט, לא בחבילות של אפליקציות, לא ב-service worker ולא במאגרים ציבוריים. דף או אפליקציה פונים לשרת שלכם; השרת פונה ל-iBus.
- החלפה: צרו מפתח חדש, והישן ממשיך לעבוד עד 24 שעות. מפתח שדלף בטלו מיד.
כתובות IP#
פרויקט יכול לקבל בקשות רק מכתובות ברשימה (IPv4, IPv6, רשתות). אז בקשה צריכה גם מפתח נכון וגם כתובת מורשית (אחרת IP_NOT_ALLOWED עם ip_seen). כדי לראות את הכתובת שהשרת רואה:
curl -H "Authorization: Bearer $IBUS_API_KEY" https://api.ibusisrael.online/api/access/whoamiהתשובה מציגה את ip_seen ואת checks לפי הסדר שבו השרת מחיל אותן: הסוד, המפתח, הפרויקט, הכתובת (allowed, denied או not_configured). דחייה נעצרת בבדיקה הראשונה שנכשלה ומציגה רק את הקוד שלה, את קידומת המפתח ואת ip_seen. הבקשה אינה צורכת מכסת נתונים, אך מוגבלת ל-30 קריאות בדקה.
קודי דחייה#
בכל דחייה יש code, detail קצר, docs (קישור לטבלה הזו) ו-request_id. ציינו את request_id כשאתם כותבים ל-iBus.
| code | HTTP | מה זה אומר ומה לעשות |
|---|---|---|
KEY_REQUIRED | 401 | לכתובת הזו נדרש מפתח. שלחו Authorization: Bearer <מפתח>; אם אין לכם מפתח, הגישו בקשה. |
KEY_INVALID | 401 | המפתח לא מוכר או הועתק עם טעות. העתיקו אותו שוב מאזור המפתחים; מפתחות שגויים חוזרים מאותה רשת מוגבלים לזמן מה. |
KEY_REVOKED | 401 | המפתח בוטל (על ידכם, אחרי החלפה או על ידי iBus). צרו מפתח חדש באזור המפתחים. |
KEY_EXPIRED | 401 | תוקף המפתח פג. צרו מפתח חדש. |
KEY_IN_QUERY | 400 | נמצא מפתח או אסימון בכתובת הבקשה. מפתח נשלח רק בכותרת Authorization; מפתח שהופיע בכתובת כדאי להחליף. |
KEY_NOT_ACCEPTED_HERE | 401 | המפתח נשלח לכתובת שאינה api.ibusisrael.online (למשל לכתובת של האפליקציה עצמה). מפתחות נבדקים רק ב-https://api.ibusisrael.online — שלחו את הבקשה לשם; בכתובות אחרות בקשה עם מפתח נדחית ולא מבוצעת בלעדיו. |
GROUP_NOT_ALLOWED | 403 | לפרויקט אין גישה לקבוצת הפעולות הזו. בקשו אותה מדף הפרויקט. |
OPERATION_NOT_AVAILABLE | 403 | הפעולה אינה ציבורית או זמינה רק לפרויקט מאושר. |
IP_NOT_ALLOWED | 403 | המפתח נכון, אבל הבקשה הגיעה מכתובת שאינה ברשימת הפרויקט. בתשובה מופיע ip_seen - הכתובת שהשרת ראה. |
PROJECT_SUSPENDED | 403 | הפרויקט הושהה על ידי iBus. הסיבה מופיעה בדף הפרויקט; המפתחות נשמרים. |
PROJECT_BLOCKED | 403 | הפרויקט חסום ומפתחותיו בוטלו. הסיבה מופיעה בדף הפרויקט, ושם אפשר להשיב. |
ACCESS_EXPIRED | 403 | תקופת הגישה של הפרויקט הסתיימה. בקשו הארכה מדף הפרויקט. |
PLATE_LOOKUP_NOT_ALLOWED | 403 | חיפוש רכב לפי לוחית רישוי אינו זמין לפרויקט. כלי רכב מוצגים בכינויים יומיים. |
RATE_LIMITED | 429 | יותר מדי בקשות בדקה - של הפרויקט (עם מפתח) או של הרשת שלכם (בלי מפתח). המתינו Retry-After שניות. |
QUOTA_EXCEEDED | 429 | התקציב היומי, החודשי או של בקשות כבדות של הפרויקט נוצל. איזה - ב-scope; מתי יתחדש - ב-Retry-After. |
CONCURRENCY_LIMIT | 429 | יותר מדי בקשות של הפרויקט בו-זמנית. המתינו לתשובות לפני ששולחים עוד. |
TEMPORARILY_RESTRICTED | 429 | הבקשות מושהות לזמן קצר אחרי הפרות חוזרות (למשל מפתחות שגויים רבים). המתינו Retry-After. |
CAPACITY_RESERVED | 503 | השירות עמוס ושומר משאבים לנוסעים. נסו שוב אחרי Retry-After שניות. |
POLICY_UNAVAILABLE | 503 | כרגע אי אפשר לבדוק את כללי הגישה, ולכן בקשות עם מפתח נדחות ולא מועברות. נסו שוב בעוד רגע. |
EXTERNAL_PAUSED | 503 | iBus השהה זמנית חיבורים חיצוניים (תקלה או תחזוקה). נסו שוב אחרי Retry-After; המפתחות והמגבלות לא משתנים. |
BODY_TOO_LARGE | 413 | גוף הבקשה גדול מהמותר. פעולות קריאה אינן צריכות גוף. |
מה אינו חלק מה-API הזה#
- חשבונות, התחברות, מועדפים, הגדרות, התראות והעוזר ליאור: פונקציות של אפליקציית iBus ב-
app.ibusisrael.online, הקשורות לסשן שלה. - מתכנן הנסיעות, מסלולי הליכה, כל הרשת בבת אחת ומיקומי כלי רכב: רק לפרויקטים שצריכים אותם, לפי בקשה. כלי רכב מוצגים בכינויים יומיים; מספרי רישוי אינם ניתנים.
- נתיבים ישנים של
api.ibusisrael.online(למשל/api/stops/searchבלי/transport) ממשיכים לעבוד לחיבורים קיימים; חיבורים חדשים משתמשים ב-/api/transport/.
דפדפנים ו-CORS#
בקשות חוצות-מקור מדפדפן מותרות רק לאפליקציית הרשת של iBus (https://app.ibusisrael.online), בלי עוגיות. מפתחות אינם לדפדפנים: דף באתר אחר פונה לשרת שלו.
מה השרת שומר#
- על כל בקשה: הזמן, הפרויקט, קידומת המפתח, הפעולה, הסטטוס, משך הזמן והחלק הרשתי של הכתובת (החלק האחרון מוסר). פירוט נשמר 7 ימים, ואחר כך רק ספירות.
- המפתח עצמו אינו נשמר (רק גיבוב) ואינו נכתב ביומנים, בדוחות או בהודעות.
- ה-API אינו מציב עוגיות. בתשובות אין מידע אישי; כלי רכב מוצגים בכינויים יומיים.
יצירת קשר#
שאלות ודיווח על בעיות: ibusisrael.online/contact. לגבי דחייה, ציינו את ה-request_id שלה.