Setting up Postman collections for the 1C-Bitrix API

Setting Up Postman Collections for 1C-Bitrix API

A Postman collection is a set of saved HTTP requests with parameters, headers, bodies, and tests. For the 1C-Bitrix API, a collection allows you to quickly test endpoint functionality without writing code — a developer opens Postman, selects a request, and clicks Send.

Postman Collection Structure

The collection is organized hierarchically:

Collection: My Bitrix API
├── Auth
│   ├── POST /auth/login
│   └── POST /auth/refresh
├── Catalog
│   ├── GET /products
│   ├── GET /products/:id
│   ├── POST /products
│   └── PUT /products/:id
├── Orders
│   ├── GET /orders
│   └── POST /orders
└── CRM
    ├── GET /leads
    └── POST /leads

Environment Variables

Postman supports environment variables — a key tool for switching between development and production servers without editing each request.

Two environments are created:

Development:

base_url = http://atlas.loc
api_key = dev-key-12345
token = (filled by script)

Production:

base_url = https://mysite.ru
api_key = prod-key-67890
token = (filled by script)

Variables are used in requests: {{base_url}}/api/v1/products.

Authorization Automation

When working with JWT authentication, the token must be obtained and substituted in each request. In Postman, this is solved via the Pre-request Script in the login request:

// Pre-request Script for POST /auth/login
pm.sendRequest({
    url: pm.environment.get('base_url') + '/api/v1/auth/login',
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            login: pm.environment.get('api_login'),
            password: pm.environment.get('api_password')
        })
    }
}, function(err, res) {
    if (!err) {
        pm.environment.set('token', res.json().token);
    }
});

For other requests, in the Authorization → Bearer Token section: {{token}}.

Alternatively, configure authorization at the collection level — then all requests inherit it.

Tests in Postman

Automatic checks are added to each request in the Tests tab:

// GET /products — basic tests
pm.test("Status 200", () => pm.response.to.have.status(200));
pm.test("Response is JSON", () => pm.response.to.be.json);

const json = pm.response.json();
pm.test("Has data array", () => {
    pm.expect(json).to.have.property('data');
    pm.expect(json.data).to.be.an('array');
});

pm.test("Product has required fields", () => {
    if (json.data.length > 0) {
        const product = json.data[0];
        pm.expect(product).to.have.all.keys(['id', 'name', 'price']);
    }
});

Collection Runner and Newman

Collection Runner allows you to run all requests in a collection sequentially and see if all tests pass. This is basic smoke testing of the API.

Newman is a CLI tool for running collections from the command line. Integrates with CI/CD:

npm install -g newman
newman run bitrix-api.postman_collection.json \
    -e production.postman_environment.json \
    --reporters cli,html

After each deployment, CI automatically runs the collection and verifies API functionality.

Export and Team Collaboration

The collection is exported as JSON (Collection v2.1) and stored in the repository alongside the code. When the API changes, the collection file is updated.

For team collaboration: publish to Postman Workspace (team feature in Postman) or share via Git.

Documentation from Collection

Postman generates documentation from the collection automatically: description of each request, response examples, parameters. This isn't full OpenAPI documentation, but sufficient for internal use.

Setting up a collection for an API with 15-20 endpoints with tests and environments — 1-2 days.