REST API עבור 1C-Bitrix: עיצוב, הטמעה, תיעוד

ל-Bitrix יש REST API מובנה עבור Bitrix24, אבל עבור אתר על "1C-Bitrix: Site Management" אין REST מקורי — יש לבנות אותו. המשימה עולה באופן קבוע: אפליקציית מובייל זקוקה לנתוני קטלוג, שירות צד שלישי רוצה לקבל הזמנות, או פרונטאנד של React או Vue זקוק לנתונים ללא טעינת עמוד. הכאב האופייני: עם כל אינטגרטור חדש צריך לכתוב פתרונות עוקפים באמצעות COption::GetOptionString ולהוציא JSON דרך echo json_encode(), ובעוד חודש הקוד הופך לספגטי.

יש לנו ניסיון של 10+ שנים בפיתוח Bitrix ולמעלה מ-50 אינטגרציות API מיושמות המטפלות בעד 10,000 RPS. אנחנו מכירים את כל המלכודות: מבעיות מטמון של אינפובלוק ועד שגיאות סריאליזציה ב-ORM. אנחנו מבטיחים פעילות יציבה תחת עומס ומספקים תיעוד Swagger לכל אנדפוינט. חיסכון ממוצע בזמן על אינטגרציה עם שירותים חיצוניים הוא 40%.

איך לבנות REST API על D7?

הבסיס של ה-API הוא קונטרולרים המבוססים על \Bitrix\Main\Engine\Controller. כל קונטרולר מטפל במשאב אחד. השוואה לפתרונות מותאמים אישית: קונטרולרי D7 מטפלים בשגיאות אוטומטית, מסריאליזציה תשובות ל-JSON, ותומכים ב-prefilters. זה מפחית את נפח הקוד פי 2-3 בהשוואה לעיבוד ידני דרך $APPLICATION->RestartBuffer().

1. צור מודול ב-/local/modules/ עם מבנה my.api. הגדר install/index.php עם מתודות InstallDB() ו-UnInstallDB() ליצירת טבלאות.
2. רשום קונטרולרים ב-routes.php (מאז קרנל 20.0). מפה URLs למחלקות, לדוגמה 'api/v1/products' => 'MyApi\Controllers\ProductController'.
3. יישם מתודות פעולה. כל מתודה מחזירה מערך — הקרנל מסריאליזציה אותו ל-JSON. הוסף prefilters לאימות והגבלות על מתודות HTTP.
4. חבר שכבת שירות — העבר לוגיקת שאילתות ועיבוד למחלקות נפרדות כמו ProductService, OrderService וכו'. זה מפשט בדיקות יחידה.
5. תעד אנדפוינטים דרך Swagger (OpenAPI 3.0). צור מפרט מהערות או ידנית. מקם את Swagger UI ב-/local/swagger/.

/local/modules/my.api/lib/
├── Controllers/
│   ├── ProductController.php → GET /api/v1/products
│   ├── OrderController.php → GET/POST /api/v1/orders
│   ├── CategoryController.php → GET /api/v1/categories
│   └── AuthController.php → POST /api/v1/auth/token
├── Services/
│   ├── ProductService.php
│   └── OrderService.php
├── Transformers/
│   ├── ProductTransformer.php → форматирование ответа
│   └── OrderTransformer.php
└── Middleware/
    ├── AuthMiddleware.php
    └── RateLimitMiddleware.php

דוגמת קונטרולר: מתודת /local/modules/my.api/lib/ ├── Controllers/ │ ├── ProductController.php → GET /api/v1/products │ ├── OrderController.php → GET/POST /api/v1/orders │ ├── CategoryController.php → GET /api/v1/categories │ └── AuthController.php → POST /api/v1/auth/token ├── Services/ │ ├── ProductService.php │ └── OrderService.php ├── Transformers/ │ ├── ProductTransformer.php → форматирование ответа │ └── OrderTransformer.php └── Middleware/ ├── AuthMiddleware.php └── RateLimitMiddleware.php מקבלת פרמטרי פג'ינציה ומחזירה נתונים עם מידע meta. הקוד קצר, ללא בדיקות מיותרות — הכל מובנה ב-D7.

namespace MyApi\Controllers;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;
use MyApi\Services\ProductService;
use MyApi\Middleware\AuthMiddleware;

class ProductController extends Controller
{
    public function configureActions(): array
    {
        return [
            'list' => ['prefilters' => [new AuthMiddleware()]],
            'detail' => ['prefilters' => [new AuthMiddleware()]],
            'create' => ['prefilters' => [new AuthMiddleware(), new ActionFilter\HttpMethod(['POST'])]],
        ];
    }

    public function listAction(int $page = 1, int $perPage = 20, string $category = ''): array
    {
        $service = new ProductService();
        $result = $service->getList($page, $perPage, $category);
        return [
            'data' => $result['items'],
            'meta' => [
                'total' => $result['total'],
                'page' => $page,
                'per_page' => $perPage,
                'pages' => ceil($result['total'] / $perPage),
            ],
        ];
    }

    public function detailAction(int $id): array
    {
        $service = new ProductService();
        $product = $service->getById($id);
        if (!$product) {
            $this->addError(new \Bitrix\Main\Error('Товар не найден', 404));
            return [];
        }
        return ['data' => $product];
    }
}

איך להבטיח אבטחת REST API?

אימות הוא מקור נפוץ לבעיות. עבור שרת-לשרת אנו משתמשים במפתחות API: כותרת פשוטה listAction. עבור בקשות משתמש (אפליקציית מובייל, SPA) — JWT. ספריית firebase/php-jwt מותקנת דרך Composer. Refresh tokens נשמרים בטבלת ORM מותאמת אישית המקושרת למשתמש. זה אמין יותר מאחסון סשנים בקבצים.

מידע נוסף על JWT: JSON Web Token (ויקיפדיה).

פורמט תשובה — עקביות חשובה. אנו עוקבים אחר תבנית אחידה: namespace MyApi\Controllers; use Bitrix\Main\Engine\Controller; use Bitrix\Main\Engine\ActionFilter; use MyApi\Services\ProductService; use MyApi\Middleware\AuthMiddleware; class ProductController extends Controller { public function configureActions(): array { return [ 'list' => ['prefilters' => [new AuthMiddleware()]], 'detail' => ['prefilters' => [new AuthMiddleware()]], 'create' => ['prefilters' => [new AuthMiddleware(), new ActionFilter\HttpMethod(['POST'])]], ]; } public function listAction(int $page = 1, int $perPage = 20, string $category = ''): array { $service = new ProductService(); $result = $service->getList($page, $perPage, $category); return [ 'data' => $result['items'], 'meta' => [ 'total' => $result['total'], 'page' => $page, 'per_page' => $perPage, 'pages' => ceil($result['total'] / $perPage), ], ]; } public function detailAction(int $id): array { $service = new ProductService(); $product = $service->getById($id); if (!$product) { $this->addError(new \Bitrix\Main\Error('Товар не найден', 404)); return []; } return ['data' => $product]; } } , X-Api-Key, status להצלחה, data לשגיאות. קונטרולר D7 מייצר תשובה אוטומטית, אבל אנו עוקפים את meta לשליטה מלאה.

protected function processAfterAction(Action $action, $result)
{
    $response = \Bitrix\Main\Application::getInstance()->getContext()->getResponse();
    $response->addHeader('Content-Type', 'application/json; charset=utf-8');

    if ($this->getErrors()) {
        echo json_encode([
            'status' => 'error',
            'errors' => array_map(fn($e) => [
                'code' => $e->getCode(),
                'message' => $e->getMessage(),
            ], $this->getErrors()),
        ], JSON_UNESCAPED_UNICODE);
    } else {
        echo json_encode([
            'status' => 'ok',
            'data' => $result,
        ], JSON_UNESCAPED_UNICODE);
    }

    exit;
}

CORS — אם ה-API נקרא מדומיין אחר, עלינו להוסיף כותרות ולטפל בבקשות OPTIONS. אחרת הדפדפן חוסם בקשות.

הגבלת קצב — הגנה מעומס. אנו משתמשים ב-Redis או, לעומס נמוך, ב-errors. לדוגמה, 1000 בקשות לשעה לכל מפתח.

איך לבדוק את ה-API?

כתוב בדיקות אינטגרציה עם PHPUnit. השתמש ב-SQLite במקום MySQL לבידוד. בדוק לא רק תרחישי הצלחה אלא גם מקרי קצה: פרמטרים לא חוקיים, משאבים חסרים, חריגה ממגבלות. דוגמת בדיקה עבור processAfterAction:

public function testListReturnsPaginationMeta(): void
{
    $controller = new ProductController();
    $result = $controller->listAction(1, 10);
    $this->assertArrayHasKey('meta', $result);
    $this->assertArrayHasKey('total', $result['meta']);
}

מה כלול

אנחנו לא רק כותבים קוד. כל פרויקט כולל:

• מפרט טכני עם אבות טיפוס לאנדפוינטים.
• דיאגרמת ארכיטקטורת מודול.
• יישום קונטרולרים, שירותים, ממירים.
• תיעוד OpenAPI 3.0 (Swagger).
• הגדרת הגבלת קצב ו-CORS.
• הוראות פריסה וחודש תמיכה.

לוחות זמנים משוערים

REST API על Bitrix נבנה מבלוקים סטנדרטיים — קונטרולרים, ORM, מטמון. המורכבות אינה בטכנולוגיה אלא בעיצוב: אנדפוינטים נכונים, פורמטי תשובה עקביים, טיפול במקרי קצה. אם אתה צריך REST API אמין לאתר Bitrix שלך, צור קשר — נבחן את הפרויקט שלך ביום אחד. הזמן פיתוח REST API וקבל תיעוד Swagger מוכן כלול.

תיעוד רשמי של Bitrix D7