Postman / Insomnia

Введение: Анализ и тестирование API

Представьте, что вы инженер, тестирующий новый двигатель. Вам нужны приборы: манометры, осциллографы, термометры. Без них вы не увидите, что происходит внутри.

В мире API такими “приборами” становятся Postman и Insomnia. Это графические инструменты для работы с API: отправка запросов, просмотр ответов, отладка, тестирование, документирование.

Для системного аналитика Postman и Insomnia — это не просто “удобные программы”. Это основной рабочий инструмент для изучения, тестирования и документирования API. Вы сможете вручную проверить, как работает API, до того, как пойдёте с требованиями к разработчикам. Вы сможете воспроизвести ошибку, которую нашёл тестировщик. Вы сможете показать бизнес-заказчику, как будет выглядеть ответ API.

Postman и Insomnia — это “лаборатория API”. Вы отправляете запрос, смотрите ответ, анализируете заголовки, проверяете время выполнения, сохраняете примеры.

Зачем аналитику Postman / Insomnia

Изучение существующего API

Тестирование гипотез

Воспроизведение ошибок

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

Postman vs Insomnia: Сравнение

Когда выбирать Postman

Когда выбирать Insomnia

Основные возможности

1. Рабочее пространство (Workspace)

Аналитик может организовать запросы по проектам:

Workspace: "Интернет-магазин"
├── Collection: "Пользователи"
│   ├── GET /users
│   ├── GET /users/{id}
│   ├── POST /users
│   ├── PUT /users/{id}
│   └── DELETE /users/{id}
├── Collection: "Заказы"
│   ├── GET /orders
│   └── POST /orders
└── Environment: "Development"
└── Environment: "Production"

2. Коллекции (Collections)

Коллекция — это группа связанных запросов. Аналитик может:

• Импортировать коллекцию из OpenAPI (Swagger)
• Экспортировать коллекцию для передачи разработчикам
• Делиться коллекцией через ссылку
• Документировать каждый запрос

3. Окружения (Environments)

Переменные окружения позволяют использовать одни и те же запросы для разных сред:

// Environment: Development
{
    "base_url": "https://dev-api.example.com",
    "api_key": "dev_key_123"
}

// Environment: Production
{
    "base_url": "https://api.example.com",
    "api_key": "prod_key_456"
}

Пример использования в запросе: {{base_url}}/users

4. Переменные (Variables)

5. Пре-скрипты и Тесты (Pre-request Scripts / Tests)

Аналитик может автоматизировать проверки:

// Пре-скрипт: установить timestamp
pm.variables.set("timestamp", Date.now());

// Тест: проверить ответ
pm.test("Статус 200", function () {
    pm.response.to.have.status(200);
});

pm.test("ID не пустой", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData.id).to.not.be.empty;
});

pm.test("Время ответа < 200мс", function () {
    pm.expect(pm.response.responseTime).to.be.below(200);
});

6. Collection Runner

Автоматический прогон всех запросов в коллекции. Аналитик может:

• Проверить, что все эндпоинты работают
• Убедиться, что изменения не сломали старые сценарии
• Измерить производительность

7. Мониторинг

Postman может запускать коллекции по расписанию (например, каждый час). Аналитик получает отчёт:

• Какие запросы упали
• Изменилось ли время ответа
• Есть ли ошибки

Практические сценарии

Сценарий 1: Изучение незнакомого API

Ситуация: Команда интегрируется с внешним API. Документация есть, но она неполная.

Действия аналитика в Postman:

1. Импортировать OpenAPI спецификацию (если есть)
2. Найти в документации примеры запросов
3. Создать запросы в Postman
4. Отправить и посмотреть реальные ответы
5. Поэкспериментировать с параметрами
6. Сохранить рабочие примеры в коллекцию

Результат: Готовая коллекция запросов для команды.

Сценарий 2: Проверка контракта перед разработкой

Ситуация: Бэкенд разрабатывает API, фронтенд ждёт спецификацию. Нужно убедиться, что контракт понятен и реализуем.

Действия аналитика:

1. Получить от разработчиков OpenAPI спецификацию
2. Импортировать в Postman
3. Сгенерировать примеры запросов (мок-сервер)
4. Показать фронтенду, как будут выглядеть запросы и ответы
5. Собрать обратную связь, вернуть разработчикам на доработку

Результат: Контракт согласован до начала разработки.

Сценарий 3: Воспроизведение ошибки

Ситуация: Тестировщик нашёл ошибку: “При отправке пустого имени сервер возвращает 500”.

Действия аналитика:

1. Создать запрос в Postman с пустым именем
2. Убедиться, что ошибка воспроизводится
3. Сохранить запрос (включая тело, заголовки)
4. Передать разработчику: “Вот точный запрос, который падает”
5. После исправления — проверить тем же запросом

Результат: Разработчик может воспроизвести ошибку локально, аналитик — проверить исправление.

Сценарий 4: Нагрузочное тестирование (ознакомительное)

Ситуация: Нужно понять, сколько запросов в секунду выдерживает API.

Действия аналитика:

1. Создать коллекцию ключевых запросов
2. Использовать Collection Runner с итерациями (например, 100 раз)
3. Измерить среднее время ответа
4. Дать рекомендацию: “API выдерживает ~50 запросов/сек”

Результат: Базовое понимание производительности до полноценного нагрузочного тестирования.

Сценарий 5: Документирование для внешних интеграторов

Ситуация: Внешний партнёр будет интегрироваться с API. Нужно дать ему примеры.

Действия аналитика:

1. Создать коллекцию всех важных сценариев
2. Добавить описания к каждому запросу
3. Добавить примеры тел запросов и ответов
4. Экспортировать коллекцию
5. Опубликовать через Postman Public API или поделиться файлом

Результат: Партнёр может импортировать коллекцию и начать интеграцию за час.

Интеграция с другими инструментами

OpenAPI (Swagger)

Для аналитика: OpenAPI → Postman = готовая коллекция для тестирования. Postman → OpenAPI = документация от реальных запросов.

cURL

Для аналитика: Разработчик прислал cURL команду — вставил в Postman, получил готовый запрос. Нашёл ошибку в Postman — скопировал как cURL, отправил разработчику.

HAR (HTTP Archive)

Postman может импортировать HAR файлы (логи запросов из браузера). Аналитик может:

• Открыть инструменты разработчика в браузере
• Сохранить HAR лог
• Импортировать в Postman

Результат: Точно воспроизведены запросы, которые делал браузер.

CI/CD (Newman / Inso)

Для аналитика: Можно настроить автоматическую проверку API при каждом деплое. Коллекция, которая работает локально, будет работать и в CI.

Организация коллекций (лучшие практики)

Структура папок

Коллекция: "API Интернет-магазина"
├── 1. Аутентификация
│   ├── POST /auth/login
│   └── POST /auth/logout
├── 2. Пользователи
│   ├── GET /users
│   ├── GET /users/{id}
│   ├── POST /users
│   ├── PUT /users/{id}
│   └── DELETE /users/{id}
├── 3. Товары
│   ├── GET /products
│   └── GET /products/{id}
├── 4. Заказы
│   ├── GET /orders
│   ├── POST /orders
│   └── GET /orders/{id}
└── 5. Сценарии (связанные запросы)
    ├── Сценарий: Создать пользователя → залогиниться → создать заказ
    └── Сценарий: Получить товар → добавить в корзину → оформить заказ

Именование запросов

Документирование в коллекции

description: |
  ## GET /users
  Возвращает список пользователей с пагинацией.
  
  ### Аутентификация
  Требуется JWT токен в заголовке `Authorization: Bearer <token>`
  
  ### Параметры
  - `limit` (int, опционально, default=20, max=100) — количество записей
  - `offset` (int, опционально, default=0) — смещение
  - `status` (string, опционально) — фильтр по статусу (active/pending/blocked)
  
  ### Ответ 200
  ```json
  {
    "data": [...],
    "pagination": {
      "limit": 20,
      "offset": 0,
      "total": 100
    }
  }

Ошибки

• 401 — не авторизован
• 403 — нет прав

## Альтернативы Postman и Insomnia

| Инструмент | Особенности | Для кого |
| :--- | :--- | :--- |
| **Postman** | Самый популярный, богатый функционал | Команды, профессионалы |
| **Insomnia** | Open Source, простота | Одиночные разработчики |
| **Hoppscotch** | В браузере, бесплатно, быстрый | Быстрые тесты |
| **Bruno** | Open Source, коллекции в Git | Git-ориентированные команды |
| **Paw** | Mac только, мощный | iOS разработчики |
| **cURL** | Командная строка | Автоматизация, скрипты |
| **HTTPie** | Улучшенный cURL | Командная строка |

## Частые ошибки (с точки зрения аналитика)

### Ошибка 1: Хранение секретов в коллекции

API ключи, пароли, токены в запросах → коллекция попадает в Git → секреты утекают.

**Решение:** Использовать переменные окружения. Секреты хранить в Environment (не в коллекции). Environment не коммитить в Git.

### Ошибка 2: Жёстко зашитые URL

`https://api.example.com/users` → при смене окружения нужно менять каждый запрос.

**Решение:** Переменная `{{base_url}}`.

### Ошибка 3: Отсутствие тестов

Коллекция есть, но никто не знает, работает ли API.

**Решение:** Добавить базовые тесты (статус 200, структура ответа).

### Ошибка 4: Запутанная структура

100 запросов в одной коллекции без папок и описаний.

**Решение:** Папки, именование, описания.

### Ошибка 5: Устаревшая коллекция

API изменился, коллекция осталась старой.

**Решение:** Перегенерация из OpenAPI. Автоматическая синхронизация (Postman Teams).

## Резюме для системного аналитика

1. **Postman / Insomnia** — основные инструменты аналитика для работы с API. Позволяют отправлять запросы, смотреть ответы, тестировать гипотезы, воспроизводить ошибки, документировать.

2. **Postman** — для командной работы, публичной документации, CI/CD. **Insomnia** — для open source проектов, простоты, приватности.

3. **Коллекции** — группы запросов. Аналитик создаёт, документирует, делится. Коллекция = знание об API.

4. **Тесты** — автоматическая проверка ответов. Аналитик может добавить проверки: статус, структура, время ответа.

5. **Collection Runner** — автоматический прогон. Аналитик может проверить всё API одной кнопкой.

6. **Интеграции:** OpenAPI (импорт/экспорт), cURL (импорт/экспорт), CI/CD (Newman/Inso).