API-First על 1C-Bitrix: REST, OAuth וקאשינג

לקוח פנה אלינו עם אתגר: אתר מסחר אלקטרוני על Bitrix, חזית React, אפליקציה מובייל ל-iOS/Android, ואינטגרציה עם 1C. רכיבים קלאסיים לא היו מתאימים—הם היו צריכים JSON. פיתחנו ארכיטקטורת API-first: Bitrix הפך לשרת backend המשרת נתונים דרך REST APIs. צוות החזית עובד מול חוזה, ללא ידע על בלוקי מידע. התוצאה—חיסכון ממוצע של 35% בעלויות תחזוקה הודות לחוזה API אחיד, וזמן הגעה לשוק עבור תכונות חדשות בפלטפורמות מובייל קטן פי 2–3. אנו מתמחים בפתרונות כאלה כבר למעלה מ-10 שנים. יש לנו 50+ פרויקטים שבהם Bitrix משמש כשרת API. זמן תגובה ממוצע של API הוא 80 אלפיות השנייה בעומסי שיא של עד 5000 RPS. צרו קשר ונשוב אליכם עם הערכת פרויקט.

API-First לעומת Bitrix קלאסי: מה ההבדל?

API-first שונה מהותית מפיתוח קלאסי. הרכיב bitrix:catalog.section מרנדר HTML בשרת. גישת ה-API מחזירה JSON—החזית שולטת ברינדור. זה נותן:

• פיתוח אפליקציות מובייל מהיר פי 2–3 בהשוואה לגישה הקלאסית.
• נקודת אינטגרציה אחת לכל הלקוחות: web, iOS, Android, שותפי B2B.
• שליטה מלאה בחזית: React/Vue SPA עם SSR, Swift, Kotlin.

מתי API-First מוצדק?

API-first על Bitrix הגיוני אם:

• ישנם מספר לקוחות חזית החולקים את אותה לוגיקה עסקית.
• יש צורך בשליטה מלאה על החזית (React/Vue SPA עם SSR).
• אפליקציית המובייל היא רכיב מוצר מלא, לא מחשבה שלאחר מעשה.
• צופים אינטגרציה עם מערכות חיצוניות רבות דרך נקודת כניסה אחת.

אם מדובר רק באתר ללא אפליקציית מובייל, API-first הוא מוגזם.

כיצד להבטיח ביצועי API?

ללא קאשינג, שרת API הופך למחולל עומסים: כל פנייה מאפליקציית מובייל משמעותה N שאילתות מסד נתונים. אסטרטגיה:

• מטמון HTTP (Cache-Control: max-age=300, ETag): למשאבים ציבוריים (קטלוג, מאמרים). CDN מאחסן בצד שלו.
• Redis/Memcached: תגובות מצטברות מורכבות (דף מוצר = נתוני iblock + מחירי קטלוג + מלאי + ביקורות). TTL 5–15 דקות, פסילת מטמון מבוססת תגים בעת שינוי נתונים.
• מטמון מתויג של Bitrix: \Bitrix\Main\Data\TaggedCache—פסילת מטמון עבור מוצר ספציפי בעת עדכון דרך חילופי 1C.

פתרונות טכניים מרכזיים

ארכיטקטורה

Клиенты
├── React SPA (веб)
├── React Native / Swift / Kotlin (мобайл)
└── Внешние системы (B2B-партнёры, ERP)
↓ HTTPS/JSON API-слой (custom REST endpoints на Bitrix)
↓ Бизнес-логика (модули catalog, sale, iblock, custom)
↓ База данных (MySQL/PostgreSQL)

יישום REST Endpoints

ב-Bitrix24 וב-1C-Bitrix (on-premise), קיים מנגנון לרישום שיטות REST מותאמות אישית דרך האירוע Клиенты ├── React SPA (веб) ├── React Native / Swift / Kotlin (мобайл) └── Внешние системы (B2B-партнёры, ERP) ↓ HTTPS/JSON API-слой (custom REST endpoints на Bitrix) ↓ Бизнес-логика (модули catalog, sale, iblock, custom) ↓ База данных (MySQL/PostgreSQL) . לפי תיעוד 1C-Bitrix, זו הדרך הסטנדרטית.

// /local/modules/vendor.api/lib/resthandler.php
class RestHandler
{
    public static function onRestServiceBuildDescription(): array
    {
        return [
            'vendor' => [
                'catalog.product.list' => [
                    'callback' => [self::class, 'getCatalogProducts'],
                    'options' => ['private' => false],
                ],
                'catalog.product.get' => [
                    'callback' => [self::class, 'getCatalogProduct'],
                    'options' => ['private' => false],
                ],
                'sale.order.create' => [
                    'callback' => [self::class, 'createOrder'],
                    'options' => ['private' => false],
                ],
            ],
        ];
    }
}

חלופה היא רכיב בקר בכתובת URL נפרדת (OnRestServiceBuildDescription) המקבל בקשות ללא שימוש במנגנון REST של Bitrix.

אימות לקוח API

השוואת שיטות:

OAuth 2.0 הוא הנתיב הסטנדרטי ל-API ציבורי. הלקוח מקבל // /local/modules/vendor.api/lib/resthandler.php class RestHandler { public static function onRestServiceBuildDescription(): array { return [ 'vendor' => [ 'catalog.product.list' => [ 'callback' => [self::class, 'getCatalogProducts'], 'options' => ['private' => false], ], 'catalog.product.get' => [ 'callback' => [self::class, 'getCatalogProduct'], 'options' => ['private' => false], ], 'sale.order.create' => [ 'callback' => [self::class, 'createOrder'], 'options' => ['private' => false], ], ], ]; } } דרך זרימת Authorization Code או Client Credentials. אסימונים נשמרים ב-/api/v1/. Bitrix תומך ב-OAuth ישירות דרך מודול access_token.

JWT לשרת לשרת ולקוחות מובייל. השרת חותם JWT עם המפתח שלו, הלקוח מעביר בכותרת b_oauth_access_token. אימות בכל בקשה—ללא גישה למסד נתונים (ללא מצב).

API Key לשותפי B2B עם IP קבוע.

כיצד לגרסאות API ללא כאב?

סכמה: oauth, Authorization: Bearer. v1 ו-v2 חיים במקביל. v1 מוכרז כמיושן עם תאריך פרישה המועבר ללקוחות דרך כותרות /api/v1/catalog/products ו-/api/v2/catalog/products.

מפרט OpenAPI

כל ה-endpoints מתועדים בפורמט OpenAPI 3.0. צוות החזית מייצר לקוח טיפוסי (TypeScript SDK, לקוחות Swift/Kotlin), מהנדסי QA מבצעים בדיקות אוטומטיות מול המפרט.

טיפול בשגיאות

פורמט שגיאה אחיד לכל ה-endpoints:

{
  "error": {
    "code": "PRODUCT_NOT_FOUND",
    "message": "Товар с ID 12345 не найден",
    "details": {}
  }
}

קודי HTTP משמשים באופן סמנטי: Deprecation—לא נמצא, Sunset—שגיאת ולידציה, { "error": { "code": "PRODUCT_NOT_FOUND", "message": "Товар с ID 12345 не найден", "details": {} } } —חריגה ממגבלת קצב, 404—השירות זמין זמנית.

בדיקות

API ללא בדיקות הוא API ללא אמון. אנו מכסים:

• בדיקות יחידה על הלוגיקה העסקית של ה-handler.
• בדיקות אינטגרציה על endpoints (PHPUnit + מסד נתונים אמיתי לבדיקות).
• בדיקות חוזה—אימות שהתגובה תואמת לסכמת OpenAPI (Dredd, Schemathesis).

תהליך העבודה

מה כלול

• עיצוב API: משאבים, endpoints, מפרט OpenAPI.
• פיתוח REST endpoints עם אימות וקאשינג.
• תיעוד Swagger UI עם דוגמאות בקשות.
• בדיקות אינטגרציה.
• העברת קוד מקור, הוראות פריסה, גישות.
• הכשרת הצוות שלך לשימוש ב-API.
• תמיכה בשלב ההשקה.

כיצד ליישם REST Endpoint ב-5 שלבים

1. הגדר משאב ו-endpoints (לדוגמה, 422).
2. צור מחלקת handler עם שיטות 429, 503, /api/v1/catalog/products, list, get.
3. רשום את ה-endpoint דרך האירוע create.
4. הוסף אימות (OAuth, JWT, API Key).
5. בדוק דרך Swagger UI ובדיקות חוזה.

שלבי פיתוח

API-first על Bitrix הוא שכבת הפשטה נוספת הדורשת משמעת צוותית. אבל מפתחי חזית עובדים עם חוזה JSON נקי ואינם יודעים דבר על רכיבים ובלוקי מידע. אנו מבטיחים איכות: כל פרויקט עובר בדיקת קוד ובדיקות עומסים. הזמינו ייעוץ ארכיטקטוני וקבלו הערכה של פתרון ה-API-first שלכם.