Postman-джедай: скрипты, переменные и другие фишки

Postman как инструмент для работы с API

 

В этой статье мы поговорим о визуально простом, но многофункциональном инструменте, который позволяет работать с API. Я познакомился с ним, потому что мне приходится много работать с интеграцией, тестированием, разработкой своих сервисов, делать большое количество запросов, где-то структурировать и хранить их.

 

 

Если нужно сделать простой Get-запрос, достаточно открыть браузер, ввести URL и получить результат. Но как только требуется сделать POST-запрос, возникает вопрос – как? Инструментов много, мой выбор пал на Postman. Долгое время я использовал его как простое хранилище запросов с группировкой в коллекции, не углубляясь в функциональность, потому что интерфейс простой и многие полезные возможности не бросаются в глаза.

Postman – это платформа для работы с API, которая позволяет гибко настраивать HTTP-запросы, отправлять их с различными параметрами, content-type, заголовками, генерировать запросы в другие языки программирования, писать на JavaScript тесты для автоматизации проверок, мониторить созданные сервисы, удобно генерировать документацию и вести совместную разработку.

 

Обзор интерфейса Postman

 

 

Интерфейс данного инструмента простой и лаконичный. При первом запуске ничего не отвлекает. Основная цель – создать новый HTTP-запрос. Остальной функционал аккуратно расположен по краю окна.

 

 

Настройка HTTP-запроса визуально состоит из двух частей. В верхней части настраивается сам запрос.

 

 

В нижней анализируется результат его выполнения.

 

 

Коротко пройдемся по тому, что можно делать с запросом. Мы выбираем тип запроса: чаще всего это GET или POST, но доступны и другие типы.

 

 

На закладке Params заполняем пары ключ-значение – они автоматически подставляются в строку адреса. Можно выполнить и обратную операцию: прописать параметры вручную, Postman подставит их автоматически.

 

 

На закладке Headers настраиваем заголовки. Нужно учитывать, что Postman скрывает часть системных заголовков, и об этом важно помнить. Здесь же можно, например, изменить user-agent на Chrome или Mozilla или полностью отключить его – в 1С это поле, насколько я помню, вообще пустое.

 

 

На закладке Authorization представлены основные типы, через которые мы можем пройти авторизацию: базовый логин и пароль, токен и другие варианты.

 

 

На закладке Body настраиваем тело POST-запросов – что именно мы отправляем. Можно выбрать нужный content-type и задать поля через интерфейс.

 

 

Или вставить свой текст запроса, например JSON, через ctrl-c / ctrl-v.

После того, как мы все это настроили, иногда нужно выполнить дополнительные действия.

 

 

Например, можно на основе запроса сгенерировать код для других языков программирования. В моей практике это чаще всего Python, либо утилита CURL для Unix-систем. Также бывает полезно посмотреть server-http-запрос, чтобы понимать, что именно и куда отправляется.

 

 

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

 

 

Рассмотрим небольшой, чисто гипотетический пример. Допустим, у нас есть пет-проект с небольшим API, в котором мы ведем наш блог и создаем записи. Эндпоинтов у нас немного:

• GET /posts – список постов

• POST /auth/login – получение токена

• POST /post – создание нового поста

• POST /notify – оповещение о новом посте

Пример выдуманный и упрощенный, но наглядный.

 

 

Все эти запросы логично объединить в единую группу. Группы в Postman называются коллекциями.

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

 

 

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

 

 

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

 

 

На закладке Variables хранятся переменные: общие для коллекции и уникальные внутри нее.

 

 

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

 

 

Обращение к переменным в Postman выполняется через фигурные скобки. В строке адреса мы пишем не привычное http, а только фигурные скобки и имя переменной.

 

Переменные

 

 

Помимо коллекции, переменные могут храниться в окружении – об этом я расскажу позже. Они могут быть глобальными для всех запросов внутри Postman, а для отдельной конфиденциальной информации можно создать локальное шифрованное хранилище и хранить логины и пароли там. В последней версии Postman во всех местах, где можно хранить переменные, кроме коллекции, их можно сделать секретными, то есть при экспорте коллекции их значение выгружаться не будет. Похоже на небольшой баг, думаю, его скоро исправят.

 

 

К переменным можно обращаться внутри скриптов. Здесь есть нюансы. При обращении к переменным окружения, коллекции и глобальным переменным через метод get(имя переменной) мы сразу получим значение. Но если использовать значение из локального хранилища, нужно сначала разрешить работу с ним в настройках. Далее, при вызове метода get во второй строке мы получим не значение, а promise – обещание. Это асинхронная технология JavaScript. В целом она несложная, просто код будет выглядеть иначе.

 

 

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

Для того, чтобы написать новую статью, то есть выполнить POST-запрос, нам нужно получить токен. Поэтому создадим эту переменную, но значение заполнять не будем, так как токен будет получаться динамически.

 

 

Рассмотрим, как это происходит. Вот небольшой POST-запрос, в котором мы используем переменные user и password, хранящиеся в локальном хранилище. Для обращения к ним нужно использовать ключевое слово vault и двоеточие. Результатом запроса будет JSON-объект, в котором лежит наш токен.

Казалось бы, можно выполнить запрос вручную, скопировать токен, зайти в коллекцию и заменить его. Но даже описывать это неудобно, а делать каждый раз руками тем более. Поэтому предлагаю начать автоматизацию и вынести эту операцию в скрипты. Вынести ее можно как в отдельный запрос, так и на уровень коллекции целиком.

 

Скрипт для автоматической установки токена

 

 

В первых двух строках мы очищаем консоль и выводим стартовое сообщение. В третьей и четвертой строках мы обращаемся к нашему хранилищу для получения значений user и password. Это как раз тот случай, о котором я упоминал выше: promise и работа с ними. Это один из вариантов обращения. В пятой строке мы описываем сам запрос с его URL и авторизацией. Далее обрабатываем ошибки, проверяем статус, и в 21–22 строках парсим тело ответа, извлекаем токен и помещаем его в переменные коллекции. Теперь этот запрос будет выполняться перед запуском всех дочерних элементов коллекции.

 

 

Как это проверить? Переходим в один из запросов, отправляем его, открываем консоль в левом нижнем углу и смотрим результат. Код выполнился, мы сходили на endpoint-логин, получили новый токен и только после этого с успехом выполнили запрос.

 

Написание и выполнение тестов для ответов API

 

 

Мы можем анализировать не только статус запроса, но и данные, которые он возвращает. Здесь два небольших примера. В первом запросе мы записываем в базу данных новый пост, и нам нужно проанализировать, что вернулось, потому что мы ожидаем определенные свойства. Здесь мы это и описываем – буквально в шесть строк кода. На правом изображении мы получаем список постов и ожидаем, что в ответе будет массив с нашими записями. Если выполнить эти запросы, на закладке Test Results в нижней части интерфейса появятся два пройденных теста. Со статусом Ok – тест, который мы описали в коллекции. Второй тест относится к конкретному запросу.

 

 

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

 

 

Результат выполнения тестов для коллекции выглядит так: видно, сколько запросов выполнялось, какие статусы они вернули, какие тесты упали, какие прошли, и все это можно выгрузить в JSON для дальнейшего анализа.

 

 

Но это еще не все. Мы можем выгрузить коллекцию в файл JSON и с помощью инструмента под названием newman, который устанавливается через пакетный менеджер npm, запускать наши тесты из консоли.

 

 

Коллекция выгружается в два клика и имеет такой формат. Здесь видно, что переменные выгружаются без значений – только ключи. Напротив переменных есть пиктограмма в виде облачка, которая позволяет расшарить их значения, если они должны попадать в облако или в файл JSON.

 

 

Далее поговорим о том, как отображается HTTP-ответ. Те, кто связан с программированием, привыкли к формату JSON. Но для людей, которые с ним не знакомы, в Postman добавили инструмент визуализации.

 

 

Встроенный AI-помощник буквально в два клика генерирует шаблон, по которому JSON превращается в удобную таблицу.

 

Работа с окружениями для переключения между средами

 

Мы наигрались на своей локальной машине c API и теперь хотим выкатить ее на сервер. Логично предположить, что URL у нас поменяется. Казалось бы, ну поменяется и ладно, можно сходить и поменять его вручную. Но каждый раз прыгать туда-сюда неудобно, это нужно автоматизировать.

 

 

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

 

 

Вынесем параметр URL в созданные нами окружения post-dev и post-prod. Помимо адреса сюда можно выносить любые другие параметры. В окружениях переменные можно делать секретными, шарить их и так далее.

 

 

Теперь в два клика можно увидеть – по сырому HTTP-запросу – что URL меняется так, как нам нужно. Это затем можно использовать в тестах, мониторах и других сценариях.

 

Flows. Low-code

 

Как я уже объяснил, для того, чтобы создать новую запись, нам сначала нужно пройти авторизацию, получить токен, создать новый пост, а после этого может улететь какое-то оповещение. Данную информацию можно передать в виде документации, записав голосовое коллеге или описав кодом. Все эти инструменты и шаги имеют право на существование, но Postman решил пойти дальше и добавить интерактивность.

 

 

В визуальном конструкторе мы можем наглядно описать всю эту цепочку.

Цепочка начинается с авторизации. Слева расположен метод вызова Send, снизу описываются переменные. Далее есть два выхода: в случае ошибки мы выводим ее в консоль, в случае успеха вызываем POST-запрос для создания новой записи и передаем туда тело первого запроса. Через точку обращаемся к токену и продолжаем цепочку.

В бесплатной версии есть ограничения: можно создавать только 50 шагов. Оно не единственное – документацию можно сгенерировать всего для трех коллекций. Наверняка есть и другие ограничения, но я их пока не встречал. Инструмент новый, интересный, документация обширная, есть часовые видео, в которых подробно описано, как можно применить этот функционал.

 

Mock servers

 

Предположим, к нашей разработке подключились другие коллеги, которые хотят дергать наш API, чтобы получать информацию, но у нас пока нет времени реализовать тот функционал, который им нужен. При этом мы уже знаем, по какому endpoint они будут обращаться и какие данные хотят получать. Чтобы закрыть их потребности, мы можем настроить так называемые mock-серверы.

 

 

Допустим, нам нужен endpoint, который при обращении будет возвращать список всех тегов, связанных с нашими постами. Для этого создаем новый запрос. Полный URL прописывать не нужно – достаточно добавить последнюю часть пути, к которой будет выполняться обращение. Затем создаем один экземпляр ответа. В нем описываем, что именно нужно возвращать: на закладке Body выбираем нужный content-type, указываем статус 200 и сохраняем.

 

 

Теперь в коллекции буквально в два клика можно создать mock-сервер.

 

 

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

Но честно говоря, мне в этом плане больше нравится аналог Postman под названием SoapUI. Интерфейс там не самый удобный, но функционала больше, и он понятнее. Либо можно использовать Python: даже если опыта немного, открываем DeepSeek, описываем нужное поведение и с помощью библиотеки Flask поднимаем все, что требуется.

 

Документация и экспорт

 

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

 

 

Единственное условие – перед генерацией нужно для всех запросов сохранить примеры ответов, иначе поля в спецификации не заполнятся, и это будет считаться ошибкой.

 

 

Делается это просто: выполняем запрос, нажимаем save response, проверяем, что выставился content-type (в данном случае JSON, хотя Postman иногда его не определяет), проверяем статус и сохраняем. Советую сохранять не только ответы со статусом 200, но и все остальные, которые мы должны корректно обрабатывать: ошибки авторизации, статусы 405 при нехватке обязательных полей и так далее. После того, как для всех запросов сохранены ответы, генерируем спецификацию.

 

 

Выгружается она в аккуратном, понятном виде. Тем, кто знаком с OpenAPI, разбираться здесь несложно. Спецификацию можно использовать для документации:

• Swagger UI - интерактивная документация в браузере,

• ReDoc - красивые API-документы,

• GitHub Pages - публикация документации,

• Генерации кода для TypeScript, Python, Java,

• Авто генерации тестов,

• Мокирования.

 

Мониторинг работоспособности API

 

Мы написали сервис, выкатили его на прод, описали документацию, все сделали, молодцы. Но как спать спокойно, если мы не знаем, что с ним происходит? Postman решает и эту задачу.

 

 

Для этого на закладке Monitors, расположенной слева, создаем новый монитор, выбираем расписание, как часто его выполнять, и указываем почту, на которую будут приходить алармы. Для примера я на своем ноутбуке сделал вид, что написал сервис с курсами валют от ЦБ РФ, записал запрос, настроил монитор и получил такие результаты выполнения.

 

 

Если сервис падает, на почту приходит уведомление.

 

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

 

Помимо HTTP-запросов можно обращаться к GraphQL и gRPC. Думаю, Postman содержит еще множество интересных вещей.

Да, у него есть конкуренты. Недавно полностью переписали его аналог на JavaScript – проект называется Bruno. Но там я столкнулся с тем, что нельзя бесплатно выгрузить спецификацию. Зато он легкий, быстрый и, по-моему, даже чуть симпатичнее Postman. Про SoapUI я уже говорил. А для нагрузочного тестирования в командах мы чаще используем Locust.

 

*************

Статья написана по итогам доклада (видео), прочитанного на конференции INFOSTART TECH EVENT.