Developing an API gateway for Bitrix24

Development of an API Gateway for Bitrix24

The Bitrix24 REST API is powerful, but working with it directly from numerous client applications is inconvenient and unsafe. Each client must know tokens, understand method specifics, work around limits. An API gateway is an intermediary layer that standardizes interaction: client applications call the gateway with an intuitive interface, the gateway translates calls to Bitrix24, aggregates data, and returns a normalized response.

Why You Need an API Gateway

Hiding Bitrix24 API complexity. Retrieving a deal with all related data (contact, company, products, tasks, activities)—this requires 5–7 separate REST calls to different methods. The gateway makes one call /deals/123, collects all data in parallel, and delivers unified JSON to the client.

Token management. Client applications don't store Bitrix24 tokens. The gateway is the only place where OAuth tokens are stored, access_tokens are refreshed via refresh_token, and their rotation is controlled.

Rate limit bypass. Cloud Bitrix24 restricts: 2 requests per second, 50 operations in batch. The gateway implements a queue and rate limiting—clients send requests as fast as they want, the gateway smooths the load.

Caching. Reference data (price types, pipeline stages, user list) changes rarely—cache at the gateway level. Requests for the same data don't reach Bitrix24.

Single monitoring point. All calls are logged, metrics (latency, error rate) collected in one place, alerts on Bitrix24 API degradation.

Gateway Architecture

The gateway is a separate HTTP service, typically PHP (Laravel/Slim) or Node.js. It sits between clients and Bitrix24.

Clients (mobile app, external site, ERP)
        ↓  HTTP/JSON (gateway's own API)
  API Gateway
    ├── Client authentication (JWT / API Key)
    ├── Input validation
    ├── Rate limiter
    ├── Cache (Redis)
    ├── Request mapper → Bitrix24 REST
    └── Batch aggregator
        ↓  OAuth2 Token
  Bitrix24 REST API

Client Authentication for Gateway

Gateway clients authenticate separately from Bitrix24. Options:

API Key. Simplest option for server-to-server. Client passes the key in the X-API-Key header. Gateway verifies the key in its database, identifies the associated Bitrix24 account and permissions.

JWT. For clients with users. User logs in (via Bitrix24 OAuth or own system), gateway issues a JWT token. Each gateway request contains JWT in the Authorization: Bearer header. Gateway decodes the token, identifies the user, and acts on their behalf in Bitrix24.

OAuth 2.0 on top of the gateway. If the gateway serves multiple client applications from different organizations, build a full OAuth server (Authorization Code Flow). Each client application is a separate OAuth client of the gateway.

Batch Requests and Parallelization

Bitrix24 supports batch: up to 50 methods in one HTTP request. The gateway aggregates parallel client calls into batch:

// Client calls 3 gateway resources "simultaneously"
// Gateway collects them into one batch to Bitrix24:
$batch = [
    'deal' => 'crm.deal.get?id=123',
    'contact' => 'crm.contact.get?id=456',
    'products' => 'crm.deal.productrows.get?id=123',
];
$result = $b24->batch($batch);

To retrieve a deal with all data, the gateway forms a batch of 4–5 methods, executes one HTTP request to Bitrix24, and assembles the result.

Redis Caching

Two levels of cache:

Directories (TTL 1 hour): pipeline stages (crm.status.list), users (user.get), price types, lead sources. This data changes rarely and is requested with every deal access.

Entities (TTL 5 minutes): data of specific deals, contacts, companies. Invalidated when receiving a webhook from Bitrix24 about object changes.

Cache key: b24:{portal_id}:{method}:{hash(params)}. On ONCRMDEALUPDATE webhook with ID=123—invalidate b24:portal1:crm.deal.get:hash({id:123}).

Data Transformation

The gateway normalizes Bitrix24 responses. From an object with string fields like 'OPPORTUNITY' => '50000.00', we get a typed response:

{
  "id": 123,
  "title": "Deal with Roga and Kopyта",
  "amount": 50000.00,
  "stage": "negotiation",
  "contact": {
    "id": 456,
    "name": "Ivan Petrov",
    "phone": "+79001234567"
  }
}

Mapping is set in the gateway configuration—this allows changing response structure without client changes.

Error Handling and Circuit Breaker

If Bitrix24 is unavailable or responds with 503 Too Many Requests, the gateway shouldn't blindly return this error to clients. Implement circuit breaker:

• Closed (normal operation): requests pass through the gateway to Bitrix24
• Open (Bitrix24 unavailable): gateway immediately returns cached data or error with clear message, doesn't create queue of waiting requests
• Half-Open (recovery verification): periodically try test request to Bitrix24

Monitoring and Metrics

The gateway exports metrics to Prometheus/Grafana or writes to ELK:

• Latency by method (p50, p95, p99)
• Error rate by code
• Request queue size
• Cache hit rate
• Current Bitrix24 limit (from X-RateLimit-Remaining header)

Development Stages

An API gateway is especially justified when multiple applications work with Bitrix24 simultaneously, or when client developers shouldn't know Bitrix24 API specifics. For one small integration scenario—it's overkill.