כיצד להגדיר גרסאות API עבור 1C-Bitrix?
לאחר עדכון אחד של קטלוג המסחר, קיבלנו תריסר שיחות: שירותי שותפים הפסיקו לעבד הזמנות. הסיבה — השדה price בתגובת ה-API שונה לשם base_price. לקוחות שפירסו את price קיבלו null במקום נתונים. גרסאות API מונעות תקלות כאלה: אתה משחרר גרסה חדשה — הישנה ממשיכה לעבוד ללא שינוי. לקוחות לא צריכים לשכתב אינטגרציות בדחיפות, ואתה נמנע מהפסדים מוניטריים. לגישות נוספות, ראה גרסאות API בוויקיפדיה.
ללא גרסאות, כל שינוי במבנה התגובה הופך לסיכון. לקוחות קשורים בחוזקה לסכימת הנתונים, ואם תשבור אותה, הם יאבדו אמון ב-API שלך. גרסאות נותנות לשותפים יכולת חיזוי: הם רואים ש-v1 עדיין פעיל, מקבלים אזהרת הפסקה, ויכולים לתכנן בשלווה מעבר ל-v2. בניסיון שלנו, מחזור חיים מובנה היטב של גרסאות מפחית את עומס התמיכה ב-30–40% — פחות בקשות דחופות, פחות תיאום ידני עם לקוחות. זה יכול לחסוך לעסקים מעל $5,000 בשנה בעלויות תמיכה.
איזו אסטרטגיית גרסאות היא הטובה ביותר?
בפועל, אנו משתמשים בשלוש גישות. ההשוואה ביניהן בטבלה:
| אסטרטגיה | דוגמה | שקיפות | המלצה |
|---|---|---|---|
| גרסאות בכתובת URL | /api/v1/products |
גבוהה | הבחירה הטובה ביותר עבור Bitrix |
| גרסאות בכותרת | Accept: application/vnd.myapi.v2+json |
בינונית | קשה יותר לניפוי |
| פרמטר שאילתה | ?version=2 |
נמוכה | פחות "נכון" |
גרסאות בכתובת URL — ההמלצה שלנו. הגרסה נראית בכתובת ה-URL, קל לבדוק ולתעד. גישה זו מאיצה אינטגרציות חדשות של שותפים פי 3 בהשוואה לפרמטרי שאילתה, ופי 2 מהירה יותר לניפוי מאשר גרסאות בכותרת.
כיצד ליישם גרסאות API ב-1C-Bitrix?
הוראות שלב אחר שלב:
- צור מבנה תיקיות
/local/api/v1/,/local/api/v2/. - הנח בקרים וקובצי routes.php בכל תיקייה.
- כתוב נתב index.php שחולץ את הגרסה מה-URL.
- חבר את תצורת הסטטוס (מופסק, נוכחי).
דוגמה למבנה קבצים:
/local/ api/ v1/ controllers/ ProductController.php OrderController.php routes.php v2/ controllers/ ProductController.php # изменённая версия routes.php index.php # роутер версий config.php # конфигурация статусов הנתב מעבד את הבקשה הנכנסת, קובע את הגרסה מה-URL, ומכליל את המסלול המתאים:
// /local/api/index.php $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH); preg_match('#^/api/(v\d+)/(.*)#', $path, $matches); $version = $matches[1] ?? 'v1'; $endpoint = $matches[2] ?? ''; $routeFile = __DIR__ . "/{$version}/routes.php"; if (!file_exists($routeFile)) { http_response_code(404); echo json_encode(['error' => 'API version not found']); exit; } require_once $routeFile; תצורת סטטוס הגרסה נשמרת בנפרד:
return [ 'v1' => ['status' => 'deprecated', 'sunset' => 'через 12 месяцев после deprecated'], 'v2' => ['status' => 'current'], ]; הנתב מוסיף אוטומטית כותרות Deprecation, Sunset ו-Link עבור גרסאות מופסקות.
כיצד פועלת ירושה בין גרסאות API?
גרסה /local/ api/ v1/ controllers/ ProductController.php OrderController.php routes.php v2/ controllers/ ProductController.php # изменённая версия routes.php index.php # роутер версий config.php # конфигурация статусов לא נכתבת מאפס. אנו משתמשים בירושת בקרים:
// v2/controllers/ProductController.php class ProductControllerV2 extends ProductControllerV1 { public function index(): array { $products = parent::index(); return array_map(function ($product) { $product['base_price'] = $product['price']; unset($product['price']); return $product; }, $products); } } תבנית זו ממזערת כפילות ומקלה על התחזוקה. הניסיון שלנו מראה שגישה זו מפחיתה את זמן הפיתוח לגרסה הבאה ב-40%.
מחזור חיים של גרסת API
אנו מיישמים מודל סטנדרטי: נוכחי → מופסק → שקיעה → פרש. בעת גישה לגרסה מופסקת, אנו מוסיפים כותרות:
header('Deprecation: true'); header('Sunset: через 12 месяцев'); header('Link: </api/v2/products>; rel="successor-version"'); | סטטוס | תיאור |
|---|---|
| נוכחי | פעיל, מומלץ ללקוחות חדשים |
| מופסק | עובד עם אזהרה |
| שקיעה | יושבת בעוד X חודשים |
| פרש | מחזיר 410 Gone |
פרטים על הגדרת כותרות מופסקות
הכותרות מוגדרות אוטומטית על ידי הנתב בהתאם לתצורה. ודא שהשדה // /local/api/index.php $path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH); preg_match('#^/api/(v\d+)/(.*)#', $path, $matches); $version = $matches[1] ?? 'v1'; $endpoint = $matches[2] ?? ''; $routeFile = __DIR__ . "/{$version}/routes.php"; if (!file_exists($routeFile)) { http_response_code(404); echo json_encode(['error' => 'API version not found']); exit; } require_once $routeFile; מכיל תאריך חוקי. לקוחות יראו אזהרה בקונסולה ויוכלו לתכנן מעבר.
מה כלול בעבודה
- ביקורת על ה-API הנוכחי והלקוחות שלו
- עיצוב תוכנית הגרסאות
- פיתוח הנתב, הבקרים והתצורה
- העברת גרסה אחת (אם כבר קיימת)
- תיעוד (OpenAPI/Swagger)
- הדרכת הצוות שלך
- אחריות על קוד (6 חודשים)
למה לעקוב אחר שימוש בגרסאות?
לאחר יישום גרסאות, חשוב לעקוב מי וכמה פעיל משתמש בכל גרסה. ללא נתונים אלה, קשה להחליט מתי לפרוש גרסה מופסקת. ניטור בסיסי מובנה ברמת הנתב: כל בקשה מתועדת עם הגרסה, כתובת ה-IP והנקודת קצה.
// В роутере после определения версии $logEntry = [ 'version' => $version, 'endpoint' => $endpoint, 'method' => $_SERVER['REQUEST_METHOD'], 'client_ip' => $_SERVER['REMOTE_ADDR'], 'timestamp' => date('Y-m-d H:i:s'), ]; // Пишем в лог-файл или отправляем в систему мониторинга error_log(json_encode($logEntry), 3, '/var/log/bitrix-api-usage.log'); בניתוח היומנים, אתה רואה: כמה בקשות ביום פוגעות ב-return [ 'v1' => ['status' => 'deprecated', 'sunset' => 'через 12 месяцев после deprecated'], 'v2' => ['status' => 'current'], ]; , אילו לקוחות לא עברו לגרסה החדשה. זה מאפשר לך להודיע לשותפים ספציפית ולהגדיר תאריכי שקיעה ריאליים מבלי לסכן משתמשים פעילים. בנוסף, איסוף מדדים יומיים: תאריכי הבקשה האחרונה מכל IP מראים מי כבר עבר ומי עדיין משתמש בגרסה הישנה. על סמך נתונים אלה, אתה יוצר רשימת לקוחות להודעה אישית. הניסיון מראה שגישה זו מאפשרת השבתה ללא כאב של גרסה מופסקת תוך 3–6 חודשים לאחר שחרור הגרסה החדשה, בעוד שבלי ניטור, גרסאות ישנות חיות שנים.
ציר הזמן להגדרת גרסאות עבור API קיים עם שתי גרסאות הוא 1 עד 3 ימים תלוי במורכבות. אנו נעריך את הפרויקט שלך בחינם — צור קשר. קבל ייעוץ מהנדס.
מדדים: מעל 10 שנות ניסיון עם Bitrix, 50+ פרויקטי אינטגרציית API שהושלמו, 5 שנים בשוק. אנו מבטיחים תאימות ל-1C-Bitrix ו-Bitrix24. חיסכון בתמיכת אינטגרציה — עד 40%.