Bezdepbonusu7Программирование: статьи и ответы

Инструменты разработчика

Как пользоваться Postman: запросы, переменные, коллекции и тесты

Postman - программа для проверки API: в ней отправляют GET и POST запросы, добавляют заголовки, JSON и авторизацию и смотрят ответ сервера. Ниже по шагам: первый запрос, тело, переменные окружения, коллекции и простые тесты на pm.test.

Как пользоваться Postman: запросы, переменные, коллекции и тесты
Содержание
  1. Что такое Postman и для чего он нужен
  2. Как выглядит окно Postman
  3. Первый GET-запрос
  4. POST-запрос с JSON в теле
  5. Заголовки запроса
  6. Авторизация запросов
  7. Переменные и окружения
  8. Коллекции: как хранить и запускать запросы
  9. Простые тесты в Postman
  10. Частые ошибки при работе в Postman
  11. Частые вопросы

Что такое Postman и для чего он нужен

Postman - программа для отправки запросов к API и просмотра ответов без написания кода. Вы вводите адрес, выбираете метод, добавляете заголовки и тело, нажимаете Send и сразу видите статус, заголовки и данные ответа. Для проверки сервера, отладки бэкенда и изучения чужого API это удобнее, чем писать скрипт на каждый запрос.

Если вы пока не уверены, что такое интерфейс программирования, начните со статьи что такое API, а про сами методы запросов прочитайте в разборе HTTP-методов GET, POST, PUT, PATCH и DELETE.

Postman работает как настольное приложение для Windows, macOS и Linux, а также в браузере. Установочный файл берут на официальном сайте postman.com. Для первых шагов хватает бесплатного аккаунта. Все запросы в этой статье идут на учебный сервис Postman Echo (postman-echo.com): он возвращает всё, что вы ему отправили, и не требует регистрации ключей.

Как выглядит окно Postman

Интерфейс состоит из трёх частей. Слева боковая панель с коллекциями, окружениями и историей. В центре вкладка запроса: строка с методом и адресом, под ней вкладки Params, Authorization, Headers, Body, Scripts и Settings. Внизу панель ответа с вкладками Body, Cookies, Headers и Test Results, а справа от неё - код статуса, время и размер ответа.

В правом верхнем углу выбирается активное окружение. Точные названия отдельных кнопок могут слегка меняться от версии к версии, но общая структура остаётся такой.

Окно Postman с запросом POST, вкладкой Body и ответом 200 OK
Главные зоны окна Postman: адрес запроса, вкладки, Send и ответ

Первый GET-запрос

GET нужен, чтобы получить данные, и тело в нём не передаётся. Создайте новый запрос кнопкой "New" или значком "+" рядом с вкладками, выберите в выпадающем списке метод GET и введите адрес.

GET https://postman-echo.com/get?name=anna&lang=python

Нажмите Send. В нижней панели появится ответ со статусом 200 OK и JSON, где в поле args вернутся ваши параметры. Параметры после знака вопроса можно не писать вручную: откройте вкладку Params и заполните таблицу Key и Value, Postman сам соберёт строку запроса и расставит ? и &.

В ответе проверяйте три вещи: статус-код, заголовок Content-Type и тело. Список кодов и их значения описаны в статье про коды ответов HTTP.

Часть ответаГде смотретьЧто означает
Statusсправа над ответом200 успех, 4xx ошибка клиента, 5xx ошибка сервера
Timeсправа над ответомвремя ответа сервера в миллисекундах
Bodyвкладка Bodyсами данные, режимы Pretty, Raw, Preview
Headersвкладка Headers ответаContent-Type, кеширование, cookies
Test Resultsвкладка Test Resultsитог выполнения проверок из скриптов

POST-запрос с JSON в теле

POST отправляет данные на сервер. Для JSON нужны три действия: выбрать метод POST, указать тело в формате JSON и сообщить серверу тип содержимого. В Postman это делается во вкладке Body.

  1. Выберите метод POST и введите адрес https://postman-echo.com/post.
  2. Откройте вкладку Body, поставьте переключатель в положение raw и справа выберите формат JSON.
  3. Вставьте тело запроса и нажмите Send.
{
  "title": "Купить хлеб",
  "done": false,
  "tags": ["дом", "срочно"]
}

Тело - обычный JSON с двойными кавычками, без комментариев и без висящей запятой после последнего элемента. Если есть сомнения в синтаксисе, проверьте текст в форматировщике JSON, а общие правила формата описаны в статье JSON - что это такое.

Форматирование и проверка JSON

Postman при выборе raw и JSON сам добавит заголовок Content-Type: application/json, это видно во вкладке Headers в скрытых заголовках. Сервер вернёт ваше тело в поле json, и вы убедитесь, что оно доставлено без искажений.

Кроме raw, у вкладки Body есть другие режимы.

РежимКогда использовать
noneзапросы без тела, например GET и DELETE
form-dataформы и загрузка файлов
x-www-form-urlencodedобычные HTML-формы, пары ключ-значение
rawJSON, XML, обычный текст
binaryотправка одного файла целиком

Заголовки запроса

Заголовки - это служебные пары "имя: значение", которые сопровождают запрос. Во вкладке Headers вы добавляете их в таблицу. Чаще всего нужны Content-Type (формат тела), Accept (какой формат ответа вы хотите) и Authorization (данные для входа).

Проверьте работу заголовков на сервисе, который возвращает их обратно.

GET https://postman-echo.com/headers
Accept: application/json
X-Client: postman-demo

В Postman запишите Accept и X-Client в таблицу Headers, а не в текст адреса. В ответе в поле headers вы увидите свои значения вместе с заголовками, которые добавил сам клиент. Если нужный заголовок отключён, снимите галочку напротив строки, не удаляя её: это удобно при отладке.

Авторизация запросов

Для защищённых методов API требует подтвердить, кто вы. В Postman для этого есть вкладка Authorization с выбором типа. Postman сам формирует нужный заголовок, вам остаётся заполнить поля.

ТипЧто вводитьКакой заголовок получится
Basic Authлогин и парольAuthorization: Basic ..., где значение - Base64 от "логин:пароль"
Bearer TokenтокенAuthorization: Bearer токен
API Keyимя ключа и значениев заголовке или в параметре запроса, на ваш выбор
OAuth 2.0параметры авторизации и получение токенаBearer-токен, полученный у сервера авторизации

Для проверки Basic Auth у Postman Echo есть метод https://postman-echo.com/basic-auth. Выберите тип Basic Auth, введите логин postman и пароль password: ответ будет 200 и поле authenticated со значением true. С неверным паролем придёт 401. Базовую кодировку значения объясняет статья про Base64: это не шифрование, поэтому Basic Auth допустим только по HTTPS.

Не вставляйте настоящие токены и пароли в тело запроса и не выкладывайте коллекции с ключами в публичный доступ. Храните секреты в переменных окружения и не делитесь экспортом, если в нём остались реальные значения.

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

Если один и тот же адрес сервера вписан в двадцать запросов, переезд на другой сервер превращается в ручную правку. Переменные решают эту проблему. Переменная записывается в двойных фигурных скобках: {{base_url}}. Постман подставит её значение перед отправкой.

Окружение (Environment) - это набор переменных, например "Локальный сервер" и "Тестовый сервер". Откройте раздел Environments на боковой панели, создайте окружение, добавьте переменную base_url со значением https://postman-echo.com и выберите это окружение в правом верхнем углу. После этого адрес запроса записывается так.

GET {{base_url}}/get?user={{user_name}}

У каждой переменной окружения есть два значения. Initial value синхронизируется с облаком и видна тем, с кем вы делитесь окружением. Current value хранится только у вас на компьютере и используется при отправке. Секреты пишите в current value.

Переменные бывают разных областей действия, они различаются так.

ОбластьГде виднаТипичное использование
Globalвезде в рабочем пространствеобщие настройки
Collectionво всех запросах коллекцииобщий адрес API
Environmentпри выбранном окруженииразные серверы и токены
Localтолько в одном запускевременные значения в скриптах

Если одна и та же переменная определена на нескольких уровнях, побеждает более узкая область: локальная перекрывает окружение, окружение - коллекцию, коллекция - глобальную.

Коллекции: как хранить и запускать запросы

Коллекция - это папка с запросами, которую можно упорядочить, экспортировать и запускать целиком. Создайте её через "New" - "Collection" или кнопкой "+" в разделе Collections, а готовый запрос сохраните сочетанием Ctrl+S, выбрав коллекцию. Внутри можно создавать вложенные папки по ресурсам API, например "Пользователи" и "Заказы".

На уровне коллекции задаются общие параметры, которые наследуют все запросы: авторизация, переменные, скрипты. Меняете тип авторизации в одном месте, а не в каждом запросе. Для этого в запросе выберите тип "Inherit auth from parent".

Запуск всех запросов подряд делает Collection Runner: нажмите Run на коллекции, выберите окружение и нажмите кнопку запуска. После прогона Postman покажет, какие запросы прошли, и сколько проверок из тестов успешно выполнено. Для автоматического запуска в CI применяют консольную утилиту Postman CLI, подробности есть в учебном центре Postman.

Экспорт коллекции создаёт JSON-файл, который можно передать коллеге или положить в репозиторий. О том, как вести общий репозиторий, написано в статье как пользоваться GitHub.

Простые тесты в Postman

Тесты - это небольшие скрипты на JavaScript, которые выполняются после получения ответа. Откройте вкладку Scripts запроса и выберите Post-response. Проверка строится на функции pm.test, в которую передаётся название и функция с утверждениями.

// Статус ответа должен быть 200
pm.test("Статус 200", function () {
    pm.response.to.have.status(200);
});

// Тело ответа - JSON, и в нём нужное значение
pm.test("Сервер вернул наш заголовок", function () {
    const data = pm.response.json();
    pm.expect(data.json.title).to.eql("Купить хлеб");
});

// Быстрый ответ
pm.test("Ответ быстрее 1500 мс", function () {
    pm.expect(pm.response.responseTime).to.be.below(1500);
});

Эти три проверки подойдут к POST-запросу из примера выше. После отправки откройте вкладку Test Results: зелёная отметка означает прошедшую проверку, красная - упавшую. Если вы не помните синтаксис, в правой части редактора скриптов есть готовые фрагменты, которые вставляются щелчком.

Скрипты умеют и сохранять данные между запросами: например, взять токен из ответа на вход и использовать его в следующих запросах.

// Post-response скрипт запроса на вход
const data = pm.response.json();
pm.environment.set("token", data.token);

// В следующих запросах: вкладка Authorization, тип Bearer Token,
// поле Token: {{token}}

Метод pm.environment.set записывает значение в активное окружение, а pm.environment.get("имя") читает его. Для переменных коллекции есть аналог pm.collectionVariables. В этом примере предполагается, что ваш сервер возвращает поле token: у Postman Echo такого поля нет, подставьте реальное имя поля из ответа вашего API.

Частые ошибки при работе в Postman

  • Тело JSON уходит как текст. В режиме raw не выбран формат JSON, и сервер отвечает 400 или 415. Проверьте переключатель справа от raw и заголовок Content-Type.
  • Переменная не подставляется. Не выбрано окружение в правом верхнем углу, либо опечатка в имени. Неразрешённая переменная остаётся в адресе в виде {{имя}}, и подсвечивается красным.
  • 401 Unauthorized. Не заполнена вкладка Authorization, токен просрочен или перепутан тип авторизации.
  • Ошибка SSL. Для локального сервера с самоподписанным сертификатом проверку можно отключить в настройках запроса, но не делайте этого для рабочих адресов.
  • Запрос работает в Postman, но не в браузере. Причина часто в CORS: Postman не соблюдает политику браузера, поэтому эти ошибки проявляются только на фронтенде.
  • Тест падает, потому что поле названо иначе. Сначала посмотрите настоящий ответ во вкладке Body и проверьте регистр имён.

Когда запросы работают, переносите их в код. Для языков есть готовые клиенты, а Postman умеет показывать запрос в виде кода: откройте значок "</>" на правой панели и выберите язык или curl. Про вызовы API из JavaScript рассказывает статья про GET и POST через Fetch API.

Частые вопросы

Как пользоваться Postman новичку?

Выберите метод, введите адрес, при необходимости заполните вкладки Params, Headers и Body и нажмите Send. Статус, время и данные ответа показываются в нижней панели.

Как отправить POST-запрос с JSON в Postman?

Выберите метод POST, откройте вкладку Body, режим raw и формат JSON, вставьте тело и нажмите Send. Заголовок Content-Type: application/json Postman добавит сам.

Где скачать Postman?

Установщики для Windows, macOS и Linux находятся на официальном сайте postman.com. Работать можно и в браузерной версии.

Как добавить токен авторизации в Postman?

Во вкладке Authorization выберите тип Bearer Token и вставьте токен. Для хранения лучше использовать переменную окружения вида {{token}}.

Что такое окружение в Postman?

Это набор переменных, например адрес сервера и токен, который можно переключать в правом верхнем углу. Так один и тот же запрос работает для разных серверов.

Как написать тест в Postman?

В запросе откройте Scripts, вкладку Post-response и используйте pm.test с утверждением, например pm.response.to.have.status(200). Результат смотрите во вкладке Test Results.

Чем Postman отличается от curl?

curl - консольная утилита, а Postman даёт графический интерфейс, коллекции, окружения и тесты. Для разовых проверок хватает обоих инструментов.

Источники

  • Postman quick start, Postman
  • Variables, Postman
  • Group sets of variables in Postman using environments, Postman

APIPostman

Похожие материалы

Версии программ и команды проверены на дату публикации. Если что-то изменилось, сверяйтесь с официальной документацией. Нашли неточность? Напишите на admin@bezdepbonusu7.win.