Документация1С-Битрикс: Модулиnative.apiРазработчикамПримеры работы

Пример карты

Карта разделена по HTTP-методам, как встроенные роуты модуля.

Разместите их в local/php_interface/api/routes/. Классы Local\Api, контроллер отчёта, коды групп и адреса замените данными своего проекта.

Схема сборки карты

local/php_interface/api/routes/
│
├─ GET/orders.php    ──┐
├─ POST/orders.php   ──┤
├─ PUT/orders.php    ──┤
├─ DELETE/orders.php ──┤
│                      │
└─ index.php ◀─────────┘
   │
   └─ «Путь карты роутов» в настройках модуля

Контроллеры в карте

Импорты для примеров:

use Local\Api\OrderController;
use Local\Api\OrderAction;
use Native\Api\Config\Internals\ControllerConfig;

Запись массивом

// Рекомендуемая запись класса и метода
ControllerConfig::CONTROLLER => [OrderController::class, 'get'],

Запись строкой

// Альтернативная запись того же класса и метода
ControllerConfig::CONTROLLER => OrderController::class . '::get',

Вызываемый класс

// Класс с методом __invoke()
ControllerConfig::CONTROLLER => OrderAction::class,

PHP-файл

// Контроллер в PHP-файле
ControllerConfig::CONTROLLER => $_SERVER['DOCUMENT_ROOT']
    . '/local/api/controllers/order.php',

GET — получение

local/php_interface/api/routes/GET/orders.php

<?php

use Native\Api\Config\Internals\OpenApiConfig;
use Native\Api\Config\Internals\CacheConfig;
use Native\Api\Config\Internals\ControllerConfig;
use Native\Api\Config\Internals\ParameterConfig;
use Native\Api\Config\Internals\ResponseConfig;
use Native\Api\Config\Internals\RouteConfig;
use Native\Api\Config\Internals\SecurityConfig;
use Native\Api\Config\Internals\TypeConfig;
use Local\Api\OrderController;
use Local\Api\StatusController;

return [
    'orders/{id}' => [
        ControllerConfig::CONTROLLER => [OrderController::class, 'get'],
        RouteConfig::DESCRIPTION => 'Получение заказа',
        RouteConfig::ACTIVE => true,
        RouteConfig::FORMAT => TypeConfig::FORMAT_XML,
        RouteConfig::SECURITY => [
            SecurityConfig::AUTH => SecurityConfig::LOGIN,
        ],
        RouteConfig::PARAMETERS => [
            'id' => [
                ParameterConfig::TYPE => TypeConfig::INTEGER,
                ParameterConfig::REQUIRED => true,
                RouteConfig::DESCRIPTION => 'ID заказа',
                ParameterConfig::EXAMPLE => 501,
            ],
        ],
        RouteConfig::CACHE => [
            CacheConfig::TTL => 300,
        ],
        RouteConfig::RESPONSE => [
            ResponseConfig::TECHNICAL_KEYS_DISABLED => false,
        ],
        OpenApiConfig::TAGS => ['Заказы'],
        OpenApiConfig::OPERATION_ID => 'getOrder',
    ],
    'status' => [
        ControllerConfig::CONTROLLER => StatusController::class,
        RouteConfig::ROUTE_TYPE => RouteConfig::ROUTE_TYPE_SERVICE,
        RouteConfig::DESCRIPTION => 'Состояние интеграции',
        RouteConfig::CACHE => [
            CacheConfig::TTL => 0,
        ],
    ],
    'reports/{id}' => [
        ControllerConfig::CONTROLLER => $_SERVER['DOCUMENT_ROOT']
            . '/local/api/controllers/report.php',
        RouteConfig::ACTIVE => false,
        RouteConfig::DESCRIPTION => 'Отчёт: описание параметров средствами OpenAPI',
        OpenApiConfig::PARAMETERS => [
            [
                OpenApiConfig::NAME => 'id',
                OpenApiConfig::IN => 'path',
                OpenApiConfig::REQUIRED => true,
                OpenApiConfig::DESCRIPTION => 'ID отчёта',
                OpenApiConfig::SCHEMA => [OpenApiConfig::TYPE => 'integer'],
                ParameterConfig::EXAMPLE => 15,
            ],
            [
                OpenApiConfig::NAME => 'page',
                OpenApiConfig::IN => 'query',
                OpenApiConfig::REQUIRED => false,
                OpenApiConfig::DESCRIPTION => 'Номер страницы',
                OpenApiConfig::SCHEMA => [
                    OpenApiConfig::TYPE => 'integer',
                    OpenApiConfig::MINIMUM => 1,
                    'default' => 1,
                ],
            ],
            [
                OpenApiConfig::NAME => 'X-Client-Version',
                OpenApiConfig::IN => 'header',
                OpenApiConfig::REQUIRED => false,
                OpenApiConfig::SCHEMA => [OpenApiConfig::TYPE => 'string'],
            ],
        ],
        OpenApiConfig::SECURITY => [
            [SecurityConfig::SECURITY_SCHEME_BEARER => []],
        ],
        OpenApiConfig::TAGS => ['Отчёты'],
        OpenApiConfig::OPERATION_ID => 'getReport',
        OpenApiConfig::DEPRECATED => true,
    ],
];

status зависит от активации сервисных роутов. Роут reports/{id} отключён: его списки parameters и security описывают документацию, но не включают проверки параметров и авторизацию.

POST — создание

local/php_interface/api/routes/POST/orders.php

<?php

use Native\Api\Config\Internals\OpenApiConfig;
use Native\Api\Config\Internals\CacheConfig;
use Native\Api\Config\Internals\ControllerConfig;
use Native\Api\Config\Internals\ParameterConfig;
use Native\Api\Config\Internals\ResponseConfig;
use Native\Api\Config\Internals\RouteConfig;
use Native\Api\Config\Internals\SecurityConfig;
use Native\Api\Config\Internals\TypeConfig;
use Local\Api\OrderController;

return [
    'orders' => [
        ControllerConfig::CONTROLLER => [OrderController::class, 'create'],
        RouteConfig::ACTIVE => true,
        RouteConfig::DESCRIPTION => 'Создание заказа',
        RouteConfig::FORMAT => TypeConfig::FORMAT_JSON,
        RouteConfig::SECURITY => [
            SecurityConfig::AUTH => SecurityConfig::TOKEN,
            SecurityConfig::TOKEN_TYPE => SecurityConfig::TOKEN_ACCESS,
            SecurityConfig::GROUP => [
                SecurityConfig::WHITELIST => ['api_clients'],
                SecurityConfig::BLACKLIST => ['api_blocked'],
            ],
        ],
        RouteConfig::PARAMETERS => [
            'customer' => [
                ParameterConfig::TYPE => TypeConfig::ARRAY,
                ParameterConfig::REQUIRED => true,
                RouteConfig::DESCRIPTION => 'Покупатель',
                RouteConfig::PARAMETERS => [
                    'name' => [
                        ParameterConfig::TYPE => TypeConfig::STRING,
                        ParameterConfig::REQUIRED => true,
                        RouteConfig::DESCRIPTION => 'Имя',
                        ParameterConfig::EXAMPLE => 'Иван',
                    ],
                    'email' => [
                        ParameterConfig::TYPE => TypeConfig::STRING,
                        ParameterConfig::REQUIRED => true,
                        RouteConfig::DESCRIPTION => 'Email',
                        ParameterConfig::EXAMPLE => 'customer@example.com',
                    ],
                ],
            ],
            OpenApiConfig::ITEMS => [
                ParameterConfig::TYPE => TypeConfig::ARRAY,
                ParameterConfig::REQUIRED => true,
                RouteConfig::DESCRIPTION => 'Позиции заказа',
                RouteConfig::PARAMETERS => [
                    [
                        'productId' => [
                            ParameterConfig::TYPE => TypeConfig::INTEGER,
                            ParameterConfig::REQUIRED => true,
                            RouteConfig::DESCRIPTION => 'ID товара',
                            ParameterConfig::EXAMPLE => 101,
                        ],
                        'quantity' => [
                            ParameterConfig::TYPE => TypeConfig::INTEGER,
                            ParameterConfig::REQUIRED => true,
                            RouteConfig::DESCRIPTION => 'Количество',
                            ParameterConfig::EXAMPLE => 2,
                        ],
                    ],
                ],
            ],
            'delivery' => [
                ParameterConfig::TYPE => TypeConfig::STRING,
                ParameterConfig::REQUIRED => true,
                ParameterConfig::POSSIBLE_VALUE => ['pickup', 'courier'],
                RouteConfig::DESCRIPTION => 'Способ получения',
                ParameterConfig::EXAMPLE => 'pickup',
            ],
            'callbackUrl' => [
                ParameterConfig::TYPE => TypeConfig::STRING,
                ParameterConfig::REQUIRED => false,
                RouteConfig::DESCRIPTION => 'Адрес уведомления о смене статуса',
                ParameterConfig::EXAMPLE => 'https://client.example.com/order-status',
            ],
        ],
        RouteConfig::CACHE => [
            CacheConfig::TTL => 0,
        ],
        RouteConfig::RESPONSE => [
            ResponseConfig::TECHNICAL_KEYS_DISABLED => true,
        ],
        OpenApiConfig::TAGS => ['Заказы'],
        OpenApiConfig::SUMMARY => 'Создать заказ',
        OpenApiConfig::OPERATION_ID => 'createOrder',
        OpenApiConfig::DEPRECATED => false,
        OpenApiConfig::EXTERNAL_DOCS => [
            OpenApiConfig::DESCRIPTION => 'Правила оформления заказа',
            OpenApiConfig::URL => 'https://example.com/docs/orders',
        ],
        OpenApiConfig::SERVERS => [
            [
                OpenApiConfig::URL => 'https://{environment}.example.com/api',
                OpenApiConfig::DESCRIPTION => 'Сервер интеграции',
                'variables' => [
                    'environment' => [
                        'default' => 'test',
                        OpenApiConfig::ENUM => ['test', 'production'],
                    ],
                ],
            ],
        ],
        OpenApiConfig::REQUEST_BODY => [
            OpenApiConfig::DESCRIPTION => 'Данные заказа',
            OpenApiConfig::REQUIRED => true,
            OpenApiConfig::CONTENT => [
                TypeConfig::CONTENT_TYPE_JSON => [
                    OpenApiConfig::SCHEMA => [
                        OpenApiConfig::REF => '#/components/schemas/CreateOrder',
                    ],
                    OpenApiConfig::EXAMPLE => [
                        'customer' => [
                            OpenApiConfig::NAME => 'Иван',
                            OpenApiConfig::EMAIL => 'customer@example.com',
                        ],
                        OpenApiConfig::ITEMS => [
                            ['productId' => 101, 'quantity' => 2],
                        ],
                        'delivery' => 'pickup',
                    ],
                ],
            ],
        ],
        OpenApiConfig::RESPONSES => [
            '201' => [
                OpenApiConfig::DESCRIPTION => 'Заказ создан',
                'headers' => [
                    'Location' => [
                        OpenApiConfig::DESCRIPTION => 'Адрес созданного заказа',
                        OpenApiConfig::SCHEMA => [OpenApiConfig::TYPE => 'string'],
                    ],
                ],
                OpenApiConfig::CONTENT => [
                    TypeConfig::CONTENT_TYPE_JSON => [
                        OpenApiConfig::SCHEMA => [OpenApiConfig::REF => '#/components/schemas/Order'],
                        OpenApiConfig::EXAMPLE => ['id' => 501, 'orderStatus' => 'new'],
                    ],
                ],
            ],
            '400' => [
                OpenApiConfig::DESCRIPTION => 'Ошибка параметров запроса',
            ],
            '401' => [
                OpenApiConfig::DESCRIPTION => 'Требуется авторизация',
            ],
            '403' => [
                OpenApiConfig::DESCRIPTION => 'Доступ запрещён',
            ],
        ],
        OpenApiConfig::CALLBACKS => [
            'orderStatusChanged' => [
                '{$request.body#/callbackUrl}' => [
                    'post' => [
                        OpenApiConfig::SUMMARY => 'Уведомление о смене статуса',
                        OpenApiConfig::REQUEST_BODY => [
                            OpenApiConfig::REQUIRED => true,
                            OpenApiConfig::CONTENT => [
                                TypeConfig::CONTENT_TYPE_JSON => [
                                    OpenApiConfig::SCHEMA => [OpenApiConfig::REF => '#/components/schemas/Order'],
                                ],
                            ],
                        ],
                        OpenApiConfig::RESPONSES => [
                            '204' => [OpenApiConfig::DESCRIPTION => 'Уведомление принято'],
                        ],
                    ],
                ],
            ],
        ],
        OpenApiConfig::COMPONENTS => [
            OpenApiConfig::SCHEMAS => [
                'CreateOrder' => [
                    OpenApiConfig::TYPE => 'object',
                    OpenApiConfig::REQUIRED => ['customer', 'items', 'delivery'],
                    OpenApiConfig::PROPERTIES => [
                        'customer' => [
                            OpenApiConfig::TYPE => 'object',
                            OpenApiConfig::REQUIRED => ['name', OpenApiConfig::EMAIL],
                            OpenApiConfig::PROPERTIES => [
                                'name' => [OpenApiConfig::TYPE => 'string'],
                                'email' => [OpenApiConfig::TYPE => 'string', OpenApiConfig::FORMAT => OpenApiConfig::EMAIL],
                            ],
                        ],
                        OpenApiConfig::ITEMS => [
                            OpenApiConfig::TYPE => 'array',
                            OpenApiConfig::MIN_ITEMS => 1,
                            OpenApiConfig::ITEMS => [
                                OpenApiConfig::TYPE => 'object',
                                OpenApiConfig::REQUIRED => ['productId', 'quantity'],
                                OpenApiConfig::PROPERTIES => [
                                    'productId' => [OpenApiConfig::TYPE => 'integer'],
                                    'quantity' => [OpenApiConfig::TYPE => 'integer'],
                                ],
                            ],
                        ],
                        'delivery' => [
                            OpenApiConfig::TYPE => 'string',
                            OpenApiConfig::ENUM => ['pickup', 'courier'],
                        ],
                        'callbackUrl' => [OpenApiConfig::TYPE => 'string', OpenApiConfig::FORMAT => 'uri'],
                    ],
                ],
                'Order' => [
                    OpenApiConfig::TYPE => 'object',
                    OpenApiConfig::REQUIRED => ['id', 'orderStatus'],
                    OpenApiConfig::PROPERTIES => [
                        'id' => [OpenApiConfig::TYPE => 'integer', 'readOnly' => true],
                        'orderStatus' => [
                            OpenApiConfig::TYPE => 'string',
                            OpenApiConfig::ENUM => ['new', 'completed', 'cancelled'],
                        ],
                    ],
                ],
            ],
        ],
        'project' => [
            'operation' => 'order.create',
        ],
    ],
];

project — пользовательское поле. callbacks, email и uri описывают документацию; обработку и проверки реализует контроллер.

PUT — изменение

local/php_interface/api/routes/PUT/orders.php

<?php

use Native\Api\Config\Internals\OpenApiConfig;
use Native\Api\Config\Internals\CacheConfig;
use Native\Api\Config\Internals\ControllerConfig;
use Native\Api\Config\Internals\ParameterConfig;
use Native\Api\Config\Internals\RouteConfig;
use Native\Api\Config\Internals\SecurityConfig;
use Native\Api\Config\Internals\TypeConfig;
use Local\Api\OrderController;

return [
    'orders/{id}' => [
        ControllerConfig::CONTROLLER => [OrderController::class, 'update'],
        RouteConfig::DESCRIPTION => 'Изменение заказа',
        RouteConfig::SECURITY => [
            SecurityConfig::AUTH => SecurityConfig::TOKEN,
            SecurityConfig::TOKEN_TYPE => SecurityConfig::TOKEN_ACCESS,
        ],
        RouteConfig::PARAMETERS => [
            'id' => [
                ParameterConfig::TYPE => TypeConfig::INTEGER,
                ParameterConfig::REQUIRED => true,
            ],
            'orderStatus' => [
                ParameterConfig::TYPE => TypeConfig::STRING,
                ParameterConfig::REQUIRED => true,
                ParameterConfig::POSSIBLE_VALUE => ['new', 'completed', 'cancelled'],
            ],
        ],
        RouteConfig::CACHE => [
            CacheConfig::TTL => 0,
        ],
        OpenApiConfig::TAGS => ['Заказы'],
    ],
];

DELETE — удаление

local/php_interface/api/routes/DELETE/orders.php

<?php

use Native\Api\Config\Internals\OpenApiConfig;
use Native\Api\Config\Internals\CacheConfig;
use Native\Api\Config\Internals\ControllerConfig;
use Native\Api\Config\Internals\ParameterConfig;
use Native\Api\Config\Internals\RouteConfig;
use Native\Api\Config\Internals\SecurityConfig;
use Native\Api\Config\Internals\TypeConfig;
use Local\Api\OrderController;

return [
    'orders/{id}' => [
        ControllerConfig::CONTROLLER => [OrderController::class, 'delete'],
        RouteConfig::DESCRIPTION => 'Удаление заказа',
        RouteConfig::SECURITY => [
            SecurityConfig::AUTH => SecurityConfig::TOKEN,
            SecurityConfig::TOKEN_TYPE => SecurityConfig::TOKEN_ACCESS,
        ],
        RouteConfig::PARAMETERS => [
            'id' => [
                ParameterConfig::TYPE => TypeConfig::INTEGER,
                ParameterConfig::REQUIRED => true,
            ],
        ],
        RouteConfig::CACHE => [
            CacheConfig::TTL => 0,
        ],
        OpenApiConfig::TAGS => ['Заказы'],
    ],
];

Общий файл карты

В поле «Путь карты роутов» укажите local/php_interface/api/routes/index.php:

При повторении адреса внутри одного метода используется первое описание. После обновления карты роутов требуется очистка кеша модуля.

<?php

use Bitrix\Main\Web\HttpClient;

$routeFiles = [
    HttpClient::HTTP_GET => ['orders.php'],
    HttpClient::HTTP_POST => ['orders.php'],
    HttpClient::HTTP_PUT => ['orders.php'],
    HttpClient::HTTP_DELETE => ['orders.php'],
];

$routes = [];

foreach ($routeFiles as $method => $files) {
    $routes[$method] = [];

    foreach ($files as $file) {
        $config = require __DIR__ . '/' . $method . '/' . $file;

        if (!is_array($config)) {
            continue;
        }

        $routes[$method] += $config;
    }
}

return $routes;