bitrix-rest

name

bitrix-rest

description

Covers REST module — registering methods from a custom module, scopes, webhook and OAuth overview, rest / restIntegration settings, link to Engine controllers and ActionFilter\Scope::REST. Applied when exposing module APIs to apps, webhooks, or marketplace integrations. Key terms — rest, OnRestServiceBuildDescription, CRestUtil, scope, webhook, OAuth, APAuth, restIntegration, Scope::REST, BX.rest.callMethod.

REST API (rest)

The rest module exposes HTTP methods under the configured path (default /rest/, option rest.rest_server_path). Baseline: main 23.0+. Prefer Engine controllers + restIntegration for new module APIs; keep classic OnRestServiceBuildDescription for explicit method maps / events / placements.

\Bitrix\Main\Loader::includeModule('rest');

Two Registration Paths

Approach	How	Typical use
Engine controller	Module .settings.php → controllers.restIntegration.enabled	New CRUD/actions; same class as AJAX
Classic description	Event rest / OnRestServiceBuildDescription	Custom method names, REST events, placements

Discovery of controller methods: Bitrix\Rest\Engine\RestManager::onFindMethodDescription requires restIntegration.enabled for that module.

Enable Controllers for REST

/local/modules/vendor.module/.settings.php:

<?php declare(strict_types=1);

return [
    'controllers' => [
        'value' => [
            'defaultNamespace' => '\\Vendor\\Module\\Infrastructure\\Controller',
            'restIntegration' => [
                'enabled' => true,
                // 'hideModuleScope' => true,  // optional; see ScopeManager
                // 'scopes' => ['myscope'],    // extra scopes advertised for the module
            ],
        ],
        'readonly' => true,
    ],
];

Call from JS: BX.rest.callMethod('vendor.module.post.create', {...}) (same action name family as BX.ajax.runAction('vendor:module.post.create') — note : vs .).

Restrict an action to REST only (or exclude REST) with Bitrix\Main\Engine\ActionFilter\Scope:

<?php declare(strict_types=1);

use Bitrix\Main\Engine\ActionFilter;

// ActionFilter\Scope::REST, ::AJAX, ::CLI, ::ALL, ::NOT_REST, ...
new ActionFilter\Scope(ActionFilter\Scope::REST);

Default AJAX CSRF filter does not apply to REST scope — design auth via REST app tokens / webhooks. Details: bitrix-controllers, bitrix-security.

Classic Method Registration

Register in module install/index.php (unregister on uninstall):

$eventManager->registerEventHandler(
    'rest',
    'OnRestServiceBuildDescription',
    'vendor.module',
    '\\Vendor\\Module\\Rest\\ServiceDescription',
    'onRestServiceBuildDescription'
);

Handler shape (same pattern as Bitrix\Main\Rest\Handlers):

<?php declare(strict_types=1);

namespace Vendor\Module\Rest;

final class ServiceDescription
{
    public static function onRestServiceBuildDescription(): array
    {
        return [
            'vendor.module' => [
                'vendor.module.item.get' => [Item::class, 'get'],
                // Optional specials:
                // \CRestUtil::EVENTS => [...],
                // \CRestUtil::PLACEMENTS => [...],
            ],
        ];
    }
}

• Top-level keys are scopes (permission units granted to the app).
• \CRestUtil::GLOBAL_SCOPE ('_global') for methods available without a dedicated scope (use sparingly).
• Method handler signature follows IRestService / classic REST callbacks ($query, $n, \CRestServer $server).

Provider aggregates all handlers via GetModuleEvents("rest", "OnRestServiceBuildDescription") (CRestProvider).

Scopes

• App installs with a list of scopes; methods outside granted scopes are rejected.
• Module can advertise scopes via restIntegration.scopes and/or classic description keys.
• Bitrix\Rest\Engine\ScopeManager builds the scope catalog from modules with REST integration.
• Module .settings.php may also define a top-level rest section (routes/documentation namespace) — see bitrix/modules/rest/.settings.php and main’s rest.defaultNamespace. This is not a substitute for registering methods.

Auth Overview: OAuth, Webhook, APAuth

Mode	Idea
OAuth	Local apps / Bitrix24-style apps; tokens via OAuth engine (Bitrix\Rest\OAuth\Auth, onRestCheckAuth)
Incoming webhook	Per-user webhook URL embedding user id + password secret; CRestUtil::getWebhookEndpoint($ap, $userId, $method) → {endpoint}{userId}/{ap}/{method}/
APAuth	Application passwords / permission tables (rest.service.apauth.* in rest .settings.php)
Session auth	Browser session for some in-product calls (Bitrix\Rest\SessionAuth\Auth)

Endpoint base: CRestUtil::getEndpoint() (site + rest_server_path).

Do not invent token formats — use admin UI / REST app tools to issue webhooks and OAuth credentials. Protect secrets; never commit webhook passwords.

Batch and Limits

CRestUtil::BATCH_MAX_LENGTH (50) limits batch size. Prefer server-side batching over huge client loops.

Checklist

• rest module installed; custom code only in /local/modules/....
• New APIs: controller + restIntegration.enabled (and filters/scopes intentional).
• Classic methods: OnRestServiceBuildDescription registered and removed on uninstall.
• Scope names stable; documented for app install.
• No reliance on AJAX CSRF for REST; auth is token/webhook/OAuth.
• Errors returned in REST-friendly form (controller addError / REST exceptions), not raw HTML.
• Webhook/OAuth secrets kept out of VCS.

Related skills

bitrix-controllers, bitrix-security, bitrix-modules, bitrix-events, bitrix-settings.