Гайд по Postman

1. Введение в Postman

Postman — платформа для разработки, тестирования, документирования и мониторинга API. Начинался как расширение для Chrome, сегодня это полноценное десктопное приложение с облачной синхронизацией, CI/CD-интеграцией, AI-ассистентом и визуальным конструированием API-запросов.

Зачем нужен Postman QA-инженеру

• Ручное тестирование API: быстрая отправка запросов, просмотр ответов, анализ заголовков и тела
• Автоматизация: Collection Runner + Newman для прогона тестов в CI
• Написание тестов: встроенный Chai.js для asserts, проверки статусов, схем JSON, времени ответа
• Переменные окружения: прогон одних и тех же тестов на dev/staging/prod
• Документация: авто-генерация документации API из коллекций
• Mock-серверы: имитация API, когда бэкенд ещё не готов
• Мониторинг: регулярная проверка, что API работает корректно
• AI-ассистент (Postbot): генерация тестов, отладка, документация через нейросеть
• gRPC и WebSocket: тестирование не только REST, но и современных протоколов

2. Установка и интерфейс

Установка

Интерфейс Postman

3. HTTP-запросы

Методы запросов

Body-форматы

Authorization

Postman поддерживает все популярные типы аутентификации:

Просмотр ответа

• Body: форматированный JSON/XML/HTML, Pretty / Raw / Preview / Visualize
• Cookies: куки, отправленные сервером
• Headers: все заголовки ответа
• Test Results: результаты выполненных тестов (PASS / FAIL)
• Status: код статуса + текст (200 OK, 404 Not Found, ...)
• Time: общее время ответа в миллисекундах
• Size: размер ответа в байтах

4. Collections

Collection — группа связанных запросов. Основная единица организации работы в Postman.

Структура коллекции

• Папки (Folders): группировка запросов для лучшей организации
• Запросы: каждый запрос со своим URL, методом, заголовками, телом
• Collection-level scripts: Pre-request и Tests, выполняемые для всех запросов в коллекции
• Variables: переменные уровня коллекции
• Authorization: настройки авторизации для всей коллекции

Работа с коллекциями

# Импорт
File → Import → File / Folder / Link / Raw text

# Экспорт
Кликнуть правой кнопкой на коллекции → Export → Collection v2.1 (рекомендуется)

# Поддержка форматов
- Postman Collection v2.1 (JSON)
- OpenAPI 3.0 / Swagger 2.0
- RAML 1.0
- GraphQL Schema
- cURL
- HAR

5. Variables

Variables — переменные, которые можно использовать во всех полях запроса: URL, заголовки, тело, скрипты. Синтаксис: {{variable_name}}.

Scopes (уровни видимости)

Работа с переменными в скриптах

// Установка значений
pm.globals.set("key", "value");
pm.collectionVariables.set("key", "value");
pm.environment.set("key", "value");
pm.variables.set("key", "value");  // local

// Получение значений
const val = pm.globals.get("key");
const envVal = pm.environment.get("key");

// Удаление
pm.globals.unset("key");
pm.environment.unset("key");

// Очистка всех переменных окружения
pm.environment.clear();

6. Environments

Environment — набор переменных для конкретного окружения (dev, staging, prod). Позволяет прогонять одни и те же запросы на разных серверах без изменения запросов.

Создание окружения

1. Нажать "Environments" в Sidebar → "+" (New Environment)
2. Задать имя: "Development" / "Staging" / "Production"
3. Добавить переменные:
   - Variable: base_url
   - Initial Value: http://localhost:8000
   - Current Value: http://localhost:8000
4. Нажать "Save"

Пример: переключение между окружениями

// Переменные в каждом окружении:
// Dev:   base_url = http://localhost:8000
// Stg:   base_url = https://staging.example.com
// Prod:  base_url = https://api.example.com

// В URL запроса:
// {{base_url}}/api/v1/users

// Тест проверяет, что ответ приходит с правильного окружения
pm.test("Response from correct environment", () => {
    const expectedUrl = pm.environment.get("base_url");
    pm.expect(pm.request.url.toString()).to.include(expectedUrl);
});

7. Pre-request и Tests скрипты

Postman использует JavaScript (Node.js-подобное окружение) для написания скриптов. Два типа скриптов выполняются в разные моменты жизненного цикла запроса.

Жизненный цикл запроса

1. Pre-request Script (коллекция)    — выполняется перед каждым запросом коллекции
2. Pre-request Script (папка)         — выполняется перед каждым запросом папки
3. Pre-request Script (запрос)        — выполняется перед запросом
4. → Запрос отправляется на сервер ←
5. Tests Script (запрос)             — выполняется после получения ответа
6. Tests Script (папка)              — выполняется после каждого запроса папки
7. Tests Script (коллекция)          — выполняется после каждого запроса коллекции

Pre-request Script — подготовка запроса

// Получение токена перед запросом
const token = pm.environment.get("auth_token");

if (!token || Date.now() > pm.environment.get("token_expires")) {
    console.log("Token expired, requesting new one...");

    const loginRequest = {
        url: pm.environment.get("auth_url") + "/login",
        method: "POST",
        header: { "Content-Type": "application/json" },
        body: {
            mode: "raw",
            raw: JSON.stringify({
                username: pm.environment.get("api_username"),
                password: pm.environment.get("api_password")
            })
        }
    };

    pm.sendRequest(loginRequest, (err, res) => {
        if (!err && res.code === 200) {
            const data = res.json();
            pm.environment.set("auth_token", data.token);
            pm.environment.set("token_expires", Date.now() + 3500000);
        }
    });
}

Tests Script — проверка ответа

Postman использует библиотеку Chai.js для утверждений (assertions):

// 1. Проверка статус-кода
pm.test("Status code is 200", () => {
    pm.response.to.have.status(200);
});

// 2. Проверка тела ответа
pm.test("Response contains users array", () => {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.be.an("array");
    pm.expect(jsonData.length).to.be.greaterThan(0);
});

// 3. Проверка заголовков
pm.test("Content-Type is JSON", () => {
    pm.response.to.have.header("Content-Type");
    pm.expect(pm.response.headers.get("Content-Type"))
      .to.include("application/json");
});

// 4. Проверка времени ответа
pm.test("Response time is acceptable", () => {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// 5. Проверка JSON Schema
const schema = {
    type: "object",
    required: ["id", "name", "email"],
    properties: {
        id: { type: "number" },
        name: { type: "string" },
        email: { type: "string", format: "email" }
    }
};

pm.test("Response matches schema", () => {
    pm.response.to.have.jsonSchema(schema);
});

// 6. Проверка с помощью tv4 (альтернативная валидация JSON Schema)
const tv4 = require("tv4");
pm.test("JSON Schema valid (tv4)", () => {
    const valid = tv4.validate(pm.response.json(), schema);
    pm.expect(valid).to.be.true;
});

Утилиты Postman Sandbox

Chaining запросов (передача данных между запросами)

// Запрос 1: POST /login → получаем токен
pm.test("Save auth token", () => {
    const data = pm.response.json();
    pm.environment.set("auth_token", data.token);
    pm.environment.set("user_id", data.user.id);
});

// Запрос 2: GET /users/{{user_id}} — использует {{auth_token}} в заголовке
// Authorization: Bearer {{auth_token}}

8. Collection Runner

Collection Runner — инструмент для запуска всех запросов коллекции с заданными параметрами. Позволяет выполнять функциональные тесты, нагрузочные тесты и интеграционные сценарии.

Запуск через UI

1. Открыть коллекцию → кнопка "Run" (▶)
2. Настроить:
   - Runner: Postman / Newman (если установлен CLI)
   - Iterations: количество прогонов
   - Delay: задержка между запросами (мс)
   - Data: CSV/JSON файл с тестовыми данными
   - Environment: окружение
3. Нажать "Run {collection_name}"

Data-driven тестирование (CSV/JSON)

// users.csv
// id,expected_status
// 1,200
// 2,200
// 999,404

// В запросе: GET /api/users/{{id}}

// В Tests:
pm.test("Status is {{expected_status}}", () => {
    pm.response.to.have.status(Number(pm.iterationData.get("expected_status")));
});

// Переменная {{id}} и {{expected_status}} автоматически подставляются на каждой итерации

Результаты прогона

• Pass / Fail / Skip: количество тестов
• Total iterations: сколько прогонов выполнено
• Failed tests: детали по упавшим тестам
• Response time: среднее / минимальное / максимальное время
• Export Results: скачать отчёт в JSON

9. Newman CLI

Newman — командная строка для запуска Postman-коллекций. Используется в CI/CD (GitHub Actions, GitLab CI, Jenkins).

Установка

# Глобально через npm
npm install -g newman

# Локально в проект
npm install --save-dev newman

# Проверка
newman --version

Запуск коллекции

# Базовый запуск
newman run collection.json -e environment.json

# С отчётом в CLI
newman run collection.json -e env.json --reporters cli

# С тестовыми данными
newman run collection.json -d data.csv --iteration-count 3

# С задержкой
newman run collection.json --delay-request 500

# Цветной вывод
newman run collection.json --color on

Отчёты (reporters)

# Установка репортёров
npm install -g newman-reporter-html newman-reporter-htmlextra

# Запуск с HTML-отчётом
newman run collection.json -e env.json \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export ./reports/report.html

Newman в CI/CD

Пример для GitHub Actions:

# .github/workflows/api-tests.yml
name: API Tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install Newman
        run: npm install -g newman newman-reporter-htmlextra
      - name: Run API tests
        run: |
          newman run api-tests/collection.json \
            -e api-tests/staging.json \
            --reporters cli,htmlextra \
            --reporter-htmlextra-export reports/api-report.html
      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: api-test-report
          path: reports/

10. Mock Servers

Mock Server — имитация API-сервера на основе существующей коллекции. Позволяет фронтенду и QA начинать работу до того, как бэкенд готов.

Создание Mock Server

1. Открыть коллекцию → "... More" → "Mock Server"
2. Настроить:
   - Name: "Users API Mock"
   - Environment (опционально)
   - Delay: задержка ответа (мс) для симуляции latency
3. Получить URL вида: https://xxxxx.mock.pstmn.io

// Postman автоматически создаёт Mock и сопоставляет запросы
// с примерами (Examples) из коллекции

Examples (примеры ответов)

Для каждого запроса можно сохранить несколько примеров ответов. Mock-сервер возвращает соответствующий пример в зависимости от запроса:

// 1. Сохранить ответ как Example
Save Response → Save as Example

// 2. Создать несколько примеров:
// - Успешный ответ (200): { "users": [...] }
// - Пустой ответ (200): { "users": [] }
// - Ошибка (404): { "error": "Not found" }

// Mock возвращает:
// - 200 с телом примера, если запрос совпал
// - 404, если пример не найден

Ограничения Free-плана

• До 1000 запросов в месяц (~30 в день)
• До 5 mock-серверов
• Базовая задержка (без настройки)

11. Monitors

Monitors — регулярная автоматическая проверка API. Postman запускает коллекцию по расписанию и уведомляет о падениях.

Создание Monitor

1. Открыть коллекцию → "... More" → "Monitor"
2. Настроить:
   - Name: "Production Health Check"
   - Environment: Production
   - Schedule: Every 5 minutes / Hourly / Daily / Custom (cron)
   - Region: выберите регион для запуска
   - Notifications: Email / Slack / Webhook
3. Сохранить

Настройка уведомлений

// Пример: тест для здоровья API
pm.test("API is healthy", () => {
    pm.response.to.have.status(200);
    pm.expect(pm.response.responseTime).to.be.below(2000);
    const data = pm.response.json();
    pm.expect(data.status).to.eql("ok");
    pm.expect(data.uptime).to.be.greaterThan(0);
});

12. Workspaces

Workspaces — организация совместной работы. Позволяют разделять коллекции, окружения и другие ресурсы между командами.

Типы Workspaces

Возможности совместной работы

• Реальное время — изменения видны всем участникам сразу
• Комментарии к запросам и коллекциям
• Activity Log — история изменений
• Роли: Admin, Editor, Viewer
• Forking и Pull Requests (аналог Git)

13. Version Control (Git)

Postman поддерживает интеграцию с Git — коллекции можно версионировать и синхронизировать с GitHub, GitLab, Bitbucket.

Git Sync (раньше — Postman to GitHub)

1. Открыть коллекцию → "... More" → "View Source Code"
2. Настроить интеграцию:
   - Repository: user/collection-repo
   - Branch: main
   - Directory: collections/
3. Sync:
   - Push: изменения из Postman → Git
   - Pull: изменения из Git → Postman

// Альтернатива: ручной экспорт/импорт
// Экспорт коллекции → commit в Git → импорт у коллег

Fork and Merge

1. Fork коллекции — создание копии для экспериментов
2. Внесение изменений в fork
3. Создание Pull Request (внутри Postman)
4. Review и Merge в основную коллекцию

// Activity Log — кто и когда менял что

14. Postman API

Postman API — REST API для программного управления ресурсами Postman: коллекциями, окружениями, mock-серверами, monitors и результатами прогонов.

Получение API Key

Postman → Settings → API Keys → Generate API Key

// Использование:
curl -H "X-Api-Key: YOUR_API_KEY" \
  https://api.getpostman.com/collections

Основные endpoints

Пример: загрузка коллекции через API

curl -X POST https://api.getpostman.com/collections \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": {
      "info": {
        "name": "My API Collection",
        "description": "Collection created via API"
      },
      "item": [{
        "name": "Get Users",
        "request": {
          "method": "GET",
          "url": {
            "raw": "https://api.example.com/users",
            "protocol": "https",
            "host": ["api", "example", "com"],
            "path": ["users"]
          }
        }
      }]
    }
  }'

15. Flows

Flows — визуальный конструктор API-процессов в Postman. Позволяет соединять запросы, условия, циклы и обработку данных без написания кода (low-code).

Базовые блоки Flows

Пример: проверка нескольких пользователей

// Flow:
// 1. Start → список user_id: [1, 2, 3, 4, 5]
// 2. Loop → для каждого id:
//    a. Send Request: GET /users/{{id}}
//    b. Condition: response.code === 200?
//       - Yes: Log "User {{id}} OK"
//       - No: Log "User {{id}} FAIL"
// 3. Return: количество успешных / всего

// Без единой строки кода — всё визуально

16. API Documentation

Postman автоматически генерирует документацию API из коллекций. Документация включает описание запросов, примеры ответов, заголовки, параметры.

Публикация документации

1. Открыть коллекцию → "... More" → "View Documentation"
2. Если нужно — добавить описание для каждого запроса (на вкладке Description)
3. Нажать "Publish" → выбрать Visiblity:
   - Private: только члены команды
   - Public: доступна всем по ссылке
4. Получить URL: https://documenter.getpostman.com/view/...

// Формат документации:
// - Left sidebar: навигация по запросам
// - Center: описание, URL, метод, заголовки, тело, примеры
// - Right panel: примеры кода на разных языках (curl, Python, JS, Go, ...)

Кастомизация документации

• Description: Markdown-описание для каждого запроса и коллекции
• Examples: несколько вариантов ответа (success, error, empty)
• Code Snippets: Postman автоматически генерирует примеры кода на 20+ языках
• Theme: светлая / тёмная тема

// Пример Markdown для описания запроса
// # Get User by ID
// Returns user profile for the given ID.
//
// ## Parameters
// - `id` (required): User identifier
//
// ## Response
// ```json
// {
//   "id": 1,
//   "name": "John Doe",
//   "email": "john@example.com"
// }
// ```
//
// ## Errors
// - 404: User not found
// - 500: Internal server error

17. Продвинутые возможности

Postman Visualizer

Кастомная визуализация ответов с помощью HTML и CSS — полезно для сложных JSON-структур:

// В Tests:
const template = `<style>
  .card { border: 1px solid #ddd; padding: 16px; margin: 8px 0; border-radius: 8px; }
  .name { font-size: 18px; font-weight: bold; }
  .email { color: #666; }
</style>
<h2>Users ({{data.length}}) </h2>
{{#each data}}
  <div class="card">
    <div class="name">{{this.name}}</div>
    <div class="email">{{this.email}}</div>
    <div>Role: {{this.role}}</div>
  </div>
{{/each}}`;

pm.visualizer.set(template, {
    data: pm.response.json()
});

Postman Console

// Открыть: View → Show Postman Console (Ctrl+Shift+C / Cmd+Option+C)
// Показывает:
// - Все запросы и ответы (включая pm.sendRequest)
// - console.log() вывод
// - Сетевые ошибки
// - Куки, заголовки

Интерцепторы

Куки (Cookies)

Postman имеет встроенный Cookie Manager для управления куками:

// Send → Cookies → Manage Cookies
// Добавить / редактировать куки для домена

// В тестах:
const cookies = pm.cookies.jar();  // CookieJar API
cookies.getAll("https://example.com", (err, cookies) => {
    console.log(cookies);
});

GraphQL в Postman

// Postman поддерживает GraphQL тремя способами:
//
// 1. Встроенный Body → GraphQL:
//    - Query: { users { id name email } }
//    - Variables: { "limit": 10 }
//
// 2. Raw JSON:
//    {"query": "...", "variables": {...}}
//
// 3. Import GraphQL Schema:
//    File → Import → GraphQL Schema → автозаполнение полей

Postman CLI (новая альтернатива Newman)

# Postman CLI — официальный CLI от Postman (замена Newman)
# Требует API Key

# Установка
curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

# Запуск
postman login --with-api-key PMAK-xxxxx
postman collection run 

Встроенные сниппеты (Snippets)

Postman предоставляет готовые сниппеты кода для Pre-request и Tests (правая панель → Snippets):

• Status code: Code is 200
• Response body: JSON value check
• Response headers: Content-Type exists
• Response time: less than 200ms
• Schema validation: JSON schema validation
• Set an environment variable
• Clear an environment variable
• Send a request

18. Postbot — AI-ассистент

Postbot (также известный как Agent Mode) — встроенный AI-ассистент Postman. Понимает контекст вашей коллекции, окружений, ответов и истории запросов. Позволяет описывать задачи на естественном языке — Postbot выполняет их автоматически.

Что умеет Postbot

Как использовать Postbot

// 1. Кнопка Postbot в правом нижнем углу (иконка робота)
// 2. Ввод запроса на естественном языке
// 3. Postbot анализирует контекст и предлагает действие

// Примеры запросов:
// "Add tests for this request"
// "Fix the failing tests in this collection"
// "Generate documentation for all requests in this folder"
// "What's wrong with this response?"
// "Create a flow that checks all users are active"

// /commands — список всех AI-навыков
// /debug — отладка запроса
// /test — генерация тестов
// /docs — документация
// /visualize — визуализация

Agent Mode — продвинутый AI

С 2025 года Postman внедрил Agent Mode — AI-агент, который работает внутри вашего workspace:

• Понимает всю коллекцию, а не один запрос
• Может вносить изменения в коллекцию (с подтверждением)
• Диагностирует цепочки запросов (chaining) и flow авторизации
• Генерирует комплексные тесты: contract tests, error handling, performance checks

// Agent Mode:
// 1. Open Agent Mode (Ctrl+Shift+Space)
// 2. Drag & drop request/collection into chat
// 3. Ask: "Review this collection and suggest tests
//    for comprehensive coverage"
// 4. Agent генерирует полный набор тестов:
//    - Status code checks
//    - Response schema validation
//    - Error handling (404, 500)
//    - Performance assertions
//    - Data integrity between requests

19. gRPC и WebSocket

gRPC в Postman

Postman поддерживает gRPC — высокопроизводительный RPC-фреймворк от Google. Работает со всеми четырьмя типами gRPC-методов: Unary, Server Streaming, Client Streaming, Bidirectional Streaming.

// 1. New → gRPC Request
// 2. Server URL: grpc.postman-echo.com (тестовый сервер)
//    или https://your-server.com
// 3. Service Definition:
//    - Server Reflection (авто): Postman загружает proto с сервера
//    - Manual: импорт .proto файла
// 4. Выбрать метод (например, SayHello)
// 5. Заполнить message payload (JSON → Protobuf авто)
// 6. Invoke

// Загрузка .proto файла:
// Просто перетащите .proto файл в Postman
// Postman автоматически разберёт все сервисы и методы

Тестирование gRPC

// Скрипты работают так же, как для REST:
// Pre-request → Выполняется до соединения
// Tests → Выполняется после завершения

pm.test("gRPC response successful", () => {
    pm.response.to.have.status("OK");  // gRPC status codes
});

pm.test("Response message fields are valid", () => {
    const data = pm.response.json();
    pm.expect(data.message).to.be.a("string");
    pm.expect(data.message).to.not.be.empty;
});

// Streaming: можно проверять каждое сообщение
pm.test("Stream message received", () => {
    // Для streaming-методов каждое сообщение
    // вызывает Tests скрипт отдельно
});

WebSocket в Postman

Postman поддерживает WebSocket, Socket.IO и другие real-time протоколы:

// 1. New → WebSocket Request
// 2. URL: wss://echo.websocket.org (тестовый сервер)
// 3. Подключиться → "Connect"
// 4. Отправка сообщения:
//    - Message → { "type": "ping" } → Send
// 5. Просмотр лога сообщений в реальном времени
// 6. Фильтрация, поиск по сообщениям

// Socket.IO
// 1. New → Socket.IO Request
// 2. URL: https://your-socketio-server.com
// 3. Events: подписка на события
// 4. Отправка событий с payload'ом

20. Безопасность API

Postman — не только инструмент для функционального тестирования, но и мощное средство для аудита безопасности API. Postman Security Workspace содержит готовую коллекцию для проверки распространённых уязвимостей.

OWASP API Security Top 10

Postman помогает проверить каждый пункт OWASP API Security Top 10:

Готовая коллекция для security-тестов

// Postman предоставляет готовую коллекцию:
// "Check for Common API Vulnerabilities"
// https://www.postman.com/postman/postman-security-workspace

// Тестирует:
// - CORS Misconfigurations
// - Directory Traversal
// - SQL Injection
// - Security Headers (Content-Security-Policy, HSTS, X-Frame-Options)
// - Rate Limiting
// - Authentication Bypass

// Требуется настроить переменные:
// - base_url — URL тестируемого API
// - malicious_origin — подозрительный origin для CORS
// - valid_access_token_value — валидный токен
// - expired_access_token_value — истёкший токен
// - other_user_access_token_value — токен другого пользователя

SQL Injection тест

pm.sendRequest({
    url: pm.environment.get("api_base_url") + "/users",
    method: "POST",
    body: {
        mode: "raw",
        raw: JSON.stringify({
            username: "' OR '1'='1",
            password: "' OR '1'='1"
        })
    }
}, function (err, res) {
    pm.test("No SQL injection vulnerability", () => {
        pm.expect(res.code).not.to.eql(500);
        pm.expect(res.code).not.to.eql(200);
    });
});

Rate Limiting тест

// В Pre-request: подготовить 100 запросов
const iterations = pm.iterationData.get("iterations");

// В Tests: проверить, что после N запросов приходит 429
pm.test("Rate limiting enforced", () => {
    if (pm.info.iteration > 10) {
        pm.expect(pm.response.code).to.eql(429);
        pm.response.to.have.header("Retry-After");
    }
});

Проверка Security Headers

pm.test("Security headers are present", () => {
    pm.response.to.have.header("Strict-Transport-Security");
    pm.response.to.have.header("X-Content-Type-Options");
    pm.response.to.have.header("X-Frame-Options");
    pm.response.to.have.header("Content-Security-Policy");
});

// Content-Security-Policy должен быть строгим
pm.test("CSP is secure", () => {
    const csp = pm.response.headers.get("Content-Security-Policy");
    pm.expect(csp).to.include("default-src 'self'");
});

21. Структура Collection JSON v2.1

Понимание структуры collection.json необходимо для работы с Git, CI/CD, и для программного создания коллекций через Postman API.

Базовая структура

{
  "info": {
    "_postman_id": "uuid",
    "name": "Collection Name",
    "description": "Описание коллекции",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "version": "1.0.0"
  },
  "item": [
    {
      "name": "Get Users",
      "request": { ... },
      "response": [ ... ],
      "event": [ ... ]
    },
    {
      "name": "User Folder",
      "item": [
        { "name": "Create User", "request": { ... } },
        { "name": "Delete User", "request": { ... } }
      ]
    }
  ],
  "variable": [ ... ],
  "event": [ ... ],
  "auth": { ... }
}

Ключевые поля

Структура request

{
  "method": "GET",
  "header": [
    { "key": "Content-Type", "value": "application/json" },
    { "key": "Authorization", "value": "Bearer {{auth_token}}" }
  ],
  "url": {
    "raw": "https://api.example.com/users?page=1",
    "protocol": "https",
    "host": ["api", "example", "com"],
    "path": ["users"],
    "query": [
      { "key": "page", "value": "1" }
    ],
    "variable": [
      { "key": "id", "value": "{{user_id}}" }
    ]
  },
  "body": {
    "mode": "raw",
    "raw": "{\"name\": \"John\"}",
    "options": { "raw": { "language": "json" } }
  },
  "auth": { "type": "bearer", "bearer": [{ "key": "token", "value": "..." }] }
}

Структура event (скрипты)

{
  "listen": "test",  // "prerequest" или "test"
  "script": {
    "exec": [
      "pm.test(\"Status code is 200\", function() {",
      "    pm.response.to.have.status(200);",
      "});"
    ],
    "type": "text/javascript",
    "packages": {}  // внешние npm-пакеты
  }
}

Collection Schema v3.0 (новый формат)

С Postman v12 появился формат 3.0 — коллекция хранится как директория с YAML-файлами:

my-collection/
├── definition.yaml        # мета-информация
├── requests/
│   ├── get-users.request.yaml
│   └── create-user.request.yaml
├── .resources/
│   ├── get-users/
│   │   ├── examples/
│   │   └── scripts/
│   └── create-user/
│       ├── examples/
│       └── scripts/
└── environments/
    └── dev.environment.yaml

// Преимущества 3.0:
// - Человеко-читаемый diff
// - Нормальные merge в Git
// - AI-агенты могут безопасно редактировать
// - Newman не поддерживает (используйте Postman CLI)

22. Private API Network

Private API Network — каталог внутренних API организации (доступен на Enterprise-плане). Это централизованное хранилище, где команды публикуют, находят и потребляют внутренние API.

Что даёт Private API Network

• Discoverability: разработчики находят нужный API через поиск по организации
• Governance: API Network Manager утверждает, какие workspace попадают в каталог
• Trust: элементы из Private API Network помечаются бейджем "доверенный источник"
• Agent Mode: AI ищет по Private API Network и отвечает на вопросы об API
• Integration: синхронизация с API Catalog для метрик и health-check

Структура Private API Network

// Иерархия:
// Organization
// └── Private API Network
//     ├── Team: Platform
//     │   ├── Workspace: "Auth Service API"
//     │   │   ├── Collection: "Auth API"
//     │   │   └── Collection: "User Management"
//     │   └── Workspace: "Payment Gateway"
//     ├── Team: Mobile
//     │   └── Workspace: "Mobile Backend API"
//     └── Team: Data
//         └── Workspace: "Data Pipeline API"

Роли

23. API-first подход

API-first — стратегия разработки, при которой спецификация API создаётся до реализации бэкенда. Postman покрывает полный lifecycle API в этой стратегии.

API Lifecycle в Postman

Workflow API-first с Postman

// 1. Design — создаём спецификацию
// Postman → APIs → Import OpenAPI / New API
// Спецификация: openapi.yml

// 2. Mock — имитация бэкенда
// Postman генерирует коллекцию из OpenAPI → Mock Server
// Фронтенд: "https://mock-api.pstmn.io/v1/users"

// 3. Develop — бэкенд под спецификацию
// Postman коллекция = тесты = single source of truth

// 4. Test — автоматизация
// Newman в CI: newman run collection.json -e env.json

// 5. Document — публикация
// Postman → View Documentation → Publish

// 6. Monitor — постоянная проверка
// Monitor → Every 5 minutes → Slack notification

// 7. Discover — в Private API Network
// Добавить workspace в Private API Network

24. Интеграции Postman

Postman интегрируется с десятками сервисов через встроенные интеграции и webhooks. Основные категории: CI/CD, трекинг задач, коммуникации, хранилища секретов.

Jira

Создавайте баги и задачи прямо из Postman при падении тестов:

// Настройка:
// 1. Integrations → Jira → Add Integration
// 2. Авторизация Atlassian аккаунта
// 3. Выбор проекта и типа задачи

// Использование:
// - Из Collection Runner: неудачный тест → Create Issue
// - Из Monitor: падение → авто-создание бага
// - Из Agent Mode: "Create a Jira issue for this failure"

// Jira issue содержит:
// - Ссылку на запрос/коллекцию/прогон
// - Тело запроса и ответа
// - Статус ошибки

Slack

// Установка: Postman App for Slack
// https://slack.com/apps → Postman

// Возможности:
// - Rich links: ссылки на коллекции/запросы/workspace
//   автоматически разворачиваются в карточки
// - Уведомления о мониторинге:
//   Monitor → Slack Channel → Автоматически
// - Слэш-команды:
//   /postman help — все команды
//   /postman list collections
//   /postman run collection-name

// Пример webhook (мониторинг в Slack):
// Integrations → Webhooks → Post monitoring results
// URL: https://hooks.slack.com/services/...

GitHub / GitLab / Bitbucket

// GitHub:
// - Git Sync: коллекция ↔ репозиторий
// - Newman в GitHub Actions (пример в разделе 9)
// - GitHub Container Registry: публикация SDK

// GitLab:
// - Newman в GitLab CI
// - GitLab Container Registry
// - API Catalog интеграция

// Bitbucket:
// - Git Sync с Bitbucket Cloud

Azure DevOps

// Azure DevOps интеграция:
// - Newman в Azure Pipelines
// - Создание Work Items из Postman
// - Azure Key Vault: хранение секретов
// - API Catalog: импорт API из Azure API Management

Webhooks (кастомные)

// Три типа webhook-интеграций:

// 1. Backup a collection
//    → При каждом изменении коллекции
//    → POST на ваш URL
//    → Используйте для backup в собственное хранилище

// 2. Post monitoring results
//    → После каждого запуска Monitor
//    → POST с результатами тестов
//    → Интеграция с PagerDuty, OpsGenie, Microsoft Teams

// 3. Post team activity
//    → При изменениях в workspace
//    → POST с описанием изменений
//    → Audit log в вашу SIEM-систему

Хранилища секретов

Другие интеграции

25. Нагрузочное тестирование

Postman не заменяет специализированные load-testing инструменты (JMeter, k6, Locust), но позволяет выполнять базовые нагрузочные тесты для проверки стабильности API под небольшой нагрузкой.

Load test через Collection Runner

// 1. Создать коллекцию с ключевыми эндпоинтами
// 2. Collection Runner → Iterations: 100 или 1000
// 3. Delay: 0 (без задержки) или 100 (имитация реальной нагрузки)
// 4. Data: CSV с разными данными на каждую итерацию
// 5. Запустить и смотреть Time (среднее/макс время ответа)

// В Tests — собираем статистику:
pm.test("Response time under load", () => {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

// Устанавливаем переменные со статистикой:
pm.test("Collect timing stats", () => {
    const time = pm.response.responseTime;
    let maxTime = Number(pm.environment.get("max_time") || 0);
    let totalTime = Number(pm.environment.get("total_time") || 0);
    let count = Number(pm.environment.get("request_count") || 0);

    if (time > maxTime) pm.environment.set("max_time", time);
    pm.environment.set("total_time", totalTime + time);
    pm.environment.set("request_count", count + 1);
});

Параллельные запросы через Newman

Newman с newman-runner-parallel позволяет запускать запросы параллельно для более реалистичной нагрузки:

# Установка
npm install -g newman newman-runner-parallel

# Параллельный запуск (4 worker)
newman-parallel run collection.json \
  -e env.json \
  --num-workers 4 \
  --iteration-count 100

# С отчётом
newman-parallel run collection.json \
  -e env.json \
  --num-workers 4 \
  --iteration-count 100 \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export ./reports/load-test.html

Пример: load test для health-эндпоинта

// Коллекция: "Load Test - Health Check"
// Один запрос: GET {{base_url}}/health
// Iterations: 500
// Delay: 0

// Tests:
pm.test("Status is 200", () => pm.response.to.have.status(200));

pm.test("Response time < 500ms", () => {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// После прогона проверяем:
// - Pass rate: 100%?
// - Max response time: не превысил ли порог?
// - Среднее время: стабильно или растёт?
// - Ошибки: появились ли 429/503/500 под нагрузкой?

k6 — профессиональный load testing от Postman

# k6 — open-source инструмент, куплен Postman в 2021
# Интеграция: экспорт коллекции → скрипт k6

# Установка k6
sudo gpg -k && sudo gpg --no-default-keyring \
  --keyring /usr/share/keyrings/k6-archive-keyring.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 \
  --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] \
  https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt update && sudo apt install k6

# Пример k6-скрипта
# import http from 'k6/http';
# import { check } from 'k6';
# export default function () {
#   const res = http.get('https://api.example.com/health');
#   check(res, { 'status is 200': (r) => r.status === 200 });
# }

# Запуск: k6 run --vus 10 --duration 30s script.js

# Экспорт Postman → k6:
# File → Export → k6 Script (.js)

26. Best Practices

Организация коллекций

• Группируйте запросы по папкам: Users, Orders, Auth, Health
• Используйте осмысленные названия: "Create User" вместо "POST to /users"
• Добавляйте описание к каждому запросу (что делает, какие параметры)
• Храните окружения отдельно от коллекций (не хардкодьте URL)
• Используйте Schema v3.0 для коллекций, хранящихся в Git

Переменные и окружения

• Используйте Collection Variables для общих настроек (base_url, api_version)
• Используйте Environments для переключения dev/staging/prod
• Секреты (токены, пароли) храните только в Current Value, не в Initial
• Именуйте переменные в SCREAMING_SNAKE_CASE: BASE_URL, AUTH_TOKEN

Тесты

• Пишите тесты для каждого запроса — минимум проверку статуса
• Используйте Chai.js asserts вместо if-условий
• Проверяйте time, headers, body, schema — не только status
• Создайте sanity-коллекцию для быстрой проверки здоровья API
• Используйте data-файлы (CSV/JSON) для параметризации тестов
• Используйте Postbot для генерации базовых тестов, но проверяйте edge case'ы

Pre-request скрипты

• Выносите авторизацию в collection-level Pre-request Script
• Обрабатывайте истечение токена — автоматически получайте новый
• Используйте console.log для отладки скриптов

CI/CD

• Храните коллекции в Git (JSON v2.1 или YAML v3.0), а не только в облаке Postman
• Используйте Newman в CI — он не зависит от Postman Cloud
• Генерируйте HTML-отчёты для визуализации результатов
• Запускайте smoke-тесты на каждый push, полный регресс — nightly
• Добавьте security-скрининг (OWASP Top 10) в пайплайн

Командная работа

• Используйте Team Workspace для совместной работы
• Комментируйте сложные запросы и тесты
• Версионируйте коллекции через Git Sync или Fork & Merge
• Документируйте API прямо в Postman — опубликуйте документацию
• Настройте Private API Network для обнаружения внутренних API

27. Глоссарий Postman-терминов

28. Чеклист Postman

Структура и организация

• Коллекции grouped по функциональным областям (папки)
• Все URL используют переменные ({{base_url}}, не хардкод)
• Описание добавлено к каждому запросу
• Созданы примеры (Examples) для разных сценариев
• Окружения настроены: dev, staging, prod
• Коллекция хранится в Git (v2.1 JSON или v3.0 YAML)

Переменные и окружения

• Collection Variables для общих настроек
• Environment Variables для переключения окружений
• Секреты (токены, пароли) — только Current Value
• Initial Value не содержит реальных данных
• Имена переменных в едином стиле (SCREAMING_SNAKE_CASE)

Тесты и скрипты

• У каждого запроса есть минимум 1 тест (статус)
• Тесты проверяют: status, body, headers, time, schema
• Pre-request Script для автополучения токена
• Collection-level скрипты для общей логики
• console.log удалены из production-тестов
• Data-файлы (CSV/JSON) для параметризации
• Postbot использован для генерации базовых тестов

Mock Servers

• Mock сервер создан для незавершённых API
• Examples настроены для разных ответов (200, 404, 500)
• Mock URL используется в конфигурации фронтенда

Monitoring

• Health-check коллекция с базовыми тестами
• Монитор запускается каждые 5-15 минут
• Уведомления настроены (Slack / Email / Webhook)
• Пороговые значения по времени ответа

Безопасность

• Проверен OWASP Top 10 через Postman Security коллекцию
• Тести SQL injection на входных параметрах
• Rate limiting проверен (ожидаемый 429)
• Security Headers проверены (CSP, HSTS, X-Frame-Options)
• CORS настроен минимально необходимый

CI/CD

• Коллекция хранится в Git (JSON v2.1 или YAML v3.0)
• Newman запускается в CI (GitHub Actions / GitLab CI)
• HTML-отчёт генерируется и сохраняется как artifact
• Регрессионные тесты — nightly, smoke — на каждый push
• Security-тесты включены в пайплайн
• Load-тесты (k6 или Newman parallel) запускаются перед релизом

Командная работа

• Используется Team Workspace
• Коллекция задокументирована (Description + Examples)
• Настроен Git Sync или Fork & Merge
• Документация API опубликована
• Private API Network настроен для внутренних API
• Интеграция с Jira для создания багов из прогонов

Гайд подготовлен для проекта qasdet.github.io • 2026