Введение в тестирование REST API в Postman: первый запрос, проверка ответа и базовые ошибки

Первый API-тест полезно начинать не с чужого кабинета и токена, а с запроса, результат которого легко объяснить. Postman Echo принимает учебные запросы и возвращает сведения о них. На таком примере можно отделить отправку HTTP-запроса от проверки бизнес-логики: сервис покажет, что получил, но не подтвердит правильность работы вашего будущего приложения.

Разберём один GET-запрос с двумя параметрами, прочитаем ответ и сохраним несколько проверок. Для упражнения не нужны ключи рабочего API, реальные заказы и личные данные. Конкретная структура Echo ниже подтверждена наблюдением ответа этого учебного адреса, а не объявляется стандартом всех REST-сервисов.

До кнопки Send: что мы отправляем

HTTP-запрос состоит не только из URL. У него есть метод, заголовки и в предусмотренных API случаях тело. В нашем опыте используется GET: параметры передаются в query string, отдельное тело запроса не нужно. Метод выбирают по контракту API, а не по желанию получить зелёный статус.

GET https://postman-echo.com/get?lesson=rest&practice=1

Здесь https — схема, postman-echo.com — имя сервиса, /get — путь, а после вопросительного знака стоят параметры lesson и practice. Знак амперсанда разделяет пары. Значение 1 в query string — текстовое представление параметра; сервер может интерпретировать его по своему контракту, но это не автоматически JSON-число.

В Postman создайте HTTP-запрос, выберите GET и вставьте адрес. В Params проверьте, что видны две строки параметров: lesson со значением rest и practice со значением 1. Изменение параметра в таблице отражается в адресе. Не добавляйте вторую копию того же параметра, если этого не требует проверяемый контракт.

Отправляем и читаем ответ по слоям

Нажмите Send. При выполненном для этого примера запросе сервис вернул HTTP 200 и JSON, в котором объект args содержал две переданные строки. В ответе Echo есть и другие сведения; в упражнении проверяем только нужную часть.

{
  "args": {
    "lesson": "rest",
    "practice": "1"
  }
}

Это сокращённый фрагмент наблюдённого ответа, а не полный документ. Сначала посмотрите статус, затем заголовки и тело. Наличие 200 означает успешный HTTP-ответ в этом обмене, но не гарантирует, что любой API выполнил требуемое бизнес-действие. Например, ошибочная реализация могла бы вернуть 200 и неверные данные.

Заголовок Content-Type помогает определить формат представления. Если ожидали JSON, а увидели HTML со страницей входа или сообщением прокси, начинать с исправления JSON-парсера рано. Сначала разберитесь, на какой адрес фактически пришёл запрос и какой участник маршрута ответил.

Время ответа в Postman полезно как наблюдение конкретного запуска. Оно зависит от условий выполнения. Один быстрый ответ не доказывает производительность сервиса под нагрузкой, а один медленный не задаёт универсальный порог отказа для всех API.

Проверки, которые объясняют причину сбоя

В Scripts → Post-response добавьте следующий JavaScript. pm.test создаёт именованную проверку, а pm.expect используется для утверждений. Названия тестов описывают ожидаемое поведение, чтобы ошибка не выглядела как безымянный красный значок.

pm.test("HTTP status is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response contains expected query arguments", function () {
    const data = pm.response.json();
    pm.expect(data).to.have.property("args");
    pm.expect(data.args.lesson).to.eql("rest");
    pm.expect(data.args.practice).to.eql("1");
});

После повторной отправки откройте результаты тестов. Первая проверка касается статуса, вторая — содержимого. Если JSON не разбирается, вызов pm.response.json() даст ошибку внутри второго теста; это повод посмотреть фактическое тело и формат ответа. Не подменяйте содержательную проверку поиском слова rest по всему тексту: оно могло бы оказаться в описании ошибки.

Если у вашей команды есть согласованный порог времени ответа, добавьте отдельную проверку. Например, pm.test("Response within demo threshold", function () { pm.expect(pm.response.responseTime).to.be.below(5000); });. Число 5000 мс здесь — авторский учебный порог, не SLA Echo и не рекомендация для любого API. Его отказ показывает превышение выбранной границы в конкретном запуске, а не доказывает причину задержки.

Мы намеренно не сравниваем весь ответ Echo целиком. Такие поля, как заголовки или сведения о запросе, могут не относиться к цели упражнения. Проверяйте конкретный контракт: нужный объект, значение и тип. Слишком широкое сравнение создаёт шум, а слишком слабое пропускает ошибку.

Path-параметр и JSON body — другие места данных

В условном маршруте /users/:userId параметр пути выбирает конкретного пользователя, например /users/42. Это пример устройства API, а не существующий адрес Echo. В Postman переменную пути задают через двоеточие и заполняют в Params. Query-параметр после вопросительного знака и значение внутри пути не взаимозаменяемы: правильное место определяет контракт сервера.

Для отдельного опыта создайте POST https://postman-echo.com/post?lesson=rest. В Body выберите raw и JSON и укажите {"course":"rest","count":1}. При выборе JSON Postman формирует соответствующий Content-Type, если его не переопределили вручную. Здесь count — число в JSON, в отличие от строки practice в query нашего GET.

Фактически проверенный POST вернул статус 200, а объект json в ответе содержал course: "rest" и count: 1. Echo отражает тело; реальный API вашего проекта может вернуть совершенно другую структуру. Не переносите проверку поля json в другой сервис без документации.

pm.test("POST body was reflected", function () {
    const data = pm.response.json();
    pm.expect(data.json.course).to.eql("rest");
    pm.expect(data.json.count).to.eql(1);
});

Этот скрипт относится к POST, а не к предыдущему GET. Сохраните два запроса отдельно, чтобы ожидание args случайно не оказалось у запроса с JSON body.

Полезный отрицательный опыт

Теперь поменяйте только lesson на http и снова отправьте запрос, оставив ожидание rest в скрипте. Для нормального ответа Echo тест статуса должен остаться успешным, а проверка параметра — показать несовпадение. Это запланированный учебный сбой: он демонстрирует, что скрипт действительно отличает два результата.

После опыта верните параметр или обновите ожидание под новый сценарий. Не оставляйте коллекцию в состоянии, где никто не знает, какие красные тесты намеренные. Описание запроса должно объяснять исходные данные и ожидаемый результат.

Другой тип проблемы — запрос вообще не отправился из-за DNS, соединения или TLS. Тогда у вас может не быть HTTP-ответа, который можно проверить как 404 или 500. Сетевой сбой, HTTP-ошибка и неверные данные успешного ответа требуют разного разбора.

Что означают коды и чего они не объясняют

Группа	Общий смысл	Первый вопрос при разборе
2xx	Успешная обработка на уровне HTTP	Соответствует ли тело ожидаемому контракту?
3xx	Перенаправления	Куда ведёт маршрут и ожидалось ли перенаправление?
4xx	Ошибки, относящиеся к запросу клиента	Верны ли адрес, метод, данные и условия доступа?
5xx	Ошибки на стороне сервера	Что сообщает ответ и воспроизводится ли проблема при тех же входных данных?

Это общая классификация. Причину конкретного 4xx или 5xx выясняют по документации API, телу ответа и доступной диагностике. Не исправляйте любой 401 случайной сменой метода.

В упражнении с GET мы читаем отражённые параметры. Когда переходите к POST, PUT или DELETE, отдельно уточняйте последствия и условия повторного выполнения. Название REST не отменяет проверки контракта конкретной операции.

Сохраняем воспроизводимый запрос

Сохраните запрос в учебную коллекцию с понятным именем, например «Echo — передача query-параметров». В описании укажите адрес, ожидаемый статус, нужные поля args и назначение отрицательного опыта. Это делает коллекцию пригодной для другого человека, а не только для автора в момент настройки.

Если позже используете переменную базового адреса, проверьте выбранное окружение и итоговое значение перед отправкой. Ошибка среды способна направить совершенно правильный тест не на тот сервис. Рабочие токены и секреты не должны попадать в общедоступный экспорт коллекции или примеры.

Postman Console помогает изучить отправленные запросы и ответы. Используйте её для сопоставления того, что настроено в интерфейсе, с фактическим обменом. При передаче диагностики коллеге удаляйте секреты и лишние пользовательские данные, а сохраняйте метод, путь, безопасные параметры, статус и понятное описание ожидаемого поведения.

Когда первый опыт можно считать понятным

Достаточно уметь объяснить каждую часть запроса и обе проверки, намеренно изменить параметр, увидеть содержательный отказ теста и вернуть сценарий в рабочее состояние. Затем замените Echo на тестовое API своего проекта и заново определите контракт ответа. Поле args из этого примера не обязано существовать в другом сервисе.

Сам GET к Echo для этой статьи проверен фактическим HTTP-запросом. Приведённый скрипт — пример для выполнения в Postman; положительный результат его запуска в вашем приложении нужно получить отдельно. Такой порядок связывает интерфейс инструмента с наблюдаемыми данными и помогает отличать настройку запроса от проверки нужного поведения.