כיצד פועל ה-API של Optifora
הדף הזה מתאר את צורת ה-API: כיצד מוכחת זהות, כיצד מתקדמות הגרסאות, באילו מגבלות נשארת בקשה, כיצד נראית שגיאה, וכיצד מוחלפים נתונים עם העולם החיצון.
המוצר בפיתוח ומשטח ה-API עדיין בהשלמה. מסמך ייחוס לנקודות הקצה יפורסם בנפרד; הדף הזה אינו נושא כתובת ואינו נושא קריאה לדוגמה, אלא את המנגנון בלבד.
אימות זהות
כל בקשה שייכת לאדם או ליישום רשום. בקשה נטולת זהות שמגיעה לנקודת קצה מוגנת חוזרת כבלתי מאומתת.
- אסימון Bearerאסימון הגישה נשלח בכותרת ההרשאה של הבקשה. הוא חתום, והוא מציין רק למי הבקשה שייכת.
- חיים קצריםתוקפו של אסימון גישה פג לאחר פרק זמן הנמדד בדקות; משך הזמן הוא הגדרת פריסה, וברירת המחדל היא שלושים דקות.
- רענון וסבב אסימוניםהפעלה מוארכת באמצעות אסימון רענון, וכל הארכה מנפיקה זוג חדש. אם אסימון רענון שכבר נוצל מוצג פעם שנייה, כל ההפעלות של אותו אדם מבוטלות.
- ההרשאות אינן צרובות באסימוןהאסימון נושא זהות בלבד; מה שמותר לאדם לראות נשאל ממסד הנתונים בכל בקשה. לכן הרשאה שנשללה מפסיקה לפעול עוד לפני שפג תוקפו של האסימון שבידיו.
- מפתח מתממשקיישום רשום מתחבר באמצעות מפתח משלו. הערך הגלוי מוצג פעם אחת בלבד, בעת היצירה; מה שנשמר הוא תמצית המפתח והקידומת הלא-סודית שמאפשרת לזהות אותו.
- הארגון הוא שמעניק גישהיהיה יישום נפוץ ככל שיהיה, בלי הרשאה שהארגון רשם הוא לא רואה ולו שורה אחת. ההרשאה נושאת תאריך, היקף מוגדר וניתנת לביטול.
ניהול גרסאות
- הגרסה נמצאת בנתיבנקודות הקצה מתפרסמות מאחורי קידומת גרסה; המשטח של היום הוא גרסה אחת.
- שינוי שובר פותח נתיב חדשהחוזה של נקודת קצה קיימת אינו נשבר במקום. שינוי שאינו תואם לאחור מתפרסם בנתיב גרסה חדש, בעוד הישן ממשיך לפעול.
- המסמך מצהיר על גרסתומסמך הייחוס נושא את מספר הגרסה שממנה נוצר; על השאלה איזו גרסה אתם קוראים עונה המסמך עצמו.
סביבות ומגבלות
מסמך הייחוס מצהיר על שתי סביבות: ייצור ופיתוח מקומי. כתובת השורש נמסרת למתממשק יחד עם המפתח שלו; היא אינה מתפרסמת בדף הזה.
- חיוניות ומוכנות נמדדות בנפרדנקודת קצה אחת מציינת שהתהליך פעיל; השנייה שולחת שאילתה אמיתית למסד הנתונים ומאשרת שהוא נגיש. רק השנייה קובעת אם יש לשלוח תעבורה.
- מקורות דפדפן מוגבלים לרשימהבקשות ממקור חוצה מתקבלות רק ממקורות שהוצהרו מראש; כל עוד הרשימה ריקה, בקשת דפדפן ממקור חוצה נדחית.
- מגבלת גוף הבקשהגוף בקשה אינו יכול לעלות על חמישה מגה-בייט. מערכים גדולים עוברים כמשימת העברה מרוכזת בעלת רשומת מצב משלה, ולא כבקשה בודדת.
- סודות אינם נכתבים ליומןיומן השרת אינו שומר כותרת הרשאה, אינו שומר עוגייה, סיסמה או מספר זהות לאומי.
מגבלת קצב
המגבלה היא לכל כתובת ולכל דקה. ברירת המחדל היא 120 בקשות בדקה, והיא נקבעת בפריסה. היתרה מדווחת בכותרות בכל תשובה.
| כותרת התשובה | מה היא מציינת |
|---|---|
| x-ratelimit-limit | המכסה הכוללת בתוך החלון. |
| x-ratelimit-remaining | מה שנותר בחלון הנוכחי. |
| x-ratelimit-reset | שניות עד לחידוש המכסה. |
| retry-after | כמה שניות להמתין לפני ניסיון חוזר. מופיעה רק בתשובה שדחתה את הבקשה. |
משנחרגה המגבלה הבקשה נדחית, והתשובה מציינת בשניות כמה זמן להמתין. ניסיון חוזר נעשה לאחר אותו זמן, ולא מיד.
מבנה השגיאה
כל שגיאה חוזרת באותה מעטפת: שדה קוד קצר שהמכונה מסתעפת לפיו, ושדה הסבר שאדם קורא.
- errorהקוד הקצר שעל פיו הלקוח מחליט.
- messageההסבר על מה שאירע.
| סטטוס | שדה הקוד | המשמעות |
|---|---|---|
| 400 | Bad Request | הבקשה אינה תואמת את הסכימה. ההסבר נוקב בשם השדה החסר או השגוי. |
| 401 | unauthenticated | אין זהות תקפה: לא נשלח אסימון, תוקפו פג, או שהאימות שלו נכשל. |
| 404 | Not Found | אין נקודת קצה כזו, או שאין רשומה כזו. |
| 429 | Too Many Requests | מגבלת הקצב נחרגה; התשובה מציינת כמה זמן להמתין. |
| 5xx | internal_error | תקלה בלתי צפויה. הפירוט אינו נמסר ללקוח; הוא נכתב ליומן השרת. |
עימוד
נקודות קצה המחזירות רשימות מקבלות את אותם שני פרמטרים ומחזירות את אותם מונים, כך שלקוח עימוד אינו נכתב מחדש לכל נקודת קצה.
- limitכמה רשומות אמור להכיל עמוד. לפחות אחת, לכל היותר מאתיים; חמישים כשלא הוגדר.
- offsetכמה רשומות לדלג. מתחיל באפס.
- totalכמה רשומות תואמות את המסננים בסך הכול.
- countכמה רשומות נושאת התשובה הזו בפועל.
התשובה גם מחזירה את הערכים limit ו-offset שבהם השתמשה; הלקוח קורא את מיקומו מן התשובה במקום לנחש אותו.
חילופי נתונים ו-webhooks
מצב החילופין הוא הגדרה ולא מוצר נפרד: כל יישום רשום נושא ברשומה שלו את המצב שבו הוא עובד.
| מצב | המשמעות |
|---|---|
| חד-כיווני — יוצא | Optifora מפרסמת נתונים; הצד השני קורא אותם או נרשם לאירועים. |
| חד-כיווני — נכנס | הצד השני דוחף נתונים; Optifora מאמתת אותם וכותבת אותם. |
| דו-כיווני | שני הצדדים כותבים; כלל יישוב ההתנגשות מוגדר מראש. |
| לחיצת יד | כל העברה פותחת הפעלה: הצעה, אימות, אישור, העברה וקבלה. אישור הקבלה נשמר אצל שני הצדדים. |
- אירועים נדחפים החוצהwebhook שולח את האירוע לכתובת החזרה שהיישום הרשום הצהיר עליה. אירוע שלא ניתן למסור נשאר בתור ונשלח שוב; לעולם אינו נזנח בשקט.
- אותה בקשה אינה נכתבת פעמייםבקשת כתיבה נושאת מפתח אי-כפילות. בקשה שנייה עם אותו מפתח אינה יוצרת רשומה שנייה.
- כל קריאה נמדדתמי קרא, מתי, באיזה היקף ובאיזו תוצאה — הכול נרשם. אותה רשומה עונה גם על איתור תקלות וגם על השאלה מי שלף את הנתונים האלה.
- היישומים שלנו נכנסים באותה דלתאין נתיב שני מיוחס. האינטגרציה שלנו עצמה היא ההוכחה למשטח שמפתח חיצוני פוגש.
מודל הנתונים של שכבת החילופין מוכן; נקודות הקצה שלה טרם פורסמו. כשיפורסמו, המקטע הזה יקשר לערכים שלהן במסמך הייחוס.
מסמכי ייחוס
מסמך הייחוס אינו נכתב ביד; הוא נוצר מסכימות נקודות הקצה. ככל שכל נקודת קצה מוסרת את הסכימה שלה, המסמך מתמלא מעצמו, כך שהמסמך וההתנהגות אינם יכולים להיפרד זה מזה.
- היום: בהכנההסכימות מתקדמות מודול אחר מודול. לפני פרסום המסמך, הבקשה והתשובה של כל נקודת קצה יופיעו בו.
- יפורסמו שני מבניםמסמך OpenAPI קריא-מכונה, ודף ייחוס הנגזר מאותו מסמך עצמו וניתן לעיון בדפדפן.
- הגישה מדורגתהסקירה הכללית פתוחה לכול. מסמך הייחוס המלא עשוי להיות מוגן באסימון תיעוד הניתן למתממשק רשום; מפתחות ייצור וכתובות חזרה אינם עניין של תיעוד כלל — הם שייכים לרשומת היישום.
- תקן הכתובותשני מסמכי ייחוס מתפרסמים וכתובותיהם קבועות: client-api.optifora.com/docs פתוח, ואילו admin-api.optifora.com/docs דורש הרשאה וסגור כלפי חוץ. אף אחד מהם אינו פעיל היום; הקישורים יתווספו למקטע הזה כשיהיו.
אם תוכנית האינטגרציה שלכם כבר ברורה, כתבו לנו מדף יצירת הקשר: תהיו בין הראשונים לדעת כשהמשטח ייפתח.
יש לכם בקשה מסוימת?
הדפים האלה מסבירים כיצד פועל תהליך התמיכה. אם יש לכם בקשה או שאלה, כתבו לנו מדף יצירת הקשר.
מעבר לדף יצירת הקשר