cover

Postman

Кидаем http-запросики и кайфуем


Содержимое

Postman (ака Постман) - топовая десктопная прога для отправки запросиков httpшных на серв

Зач это надо?

В браузере что-то сложнее GET-запроса не кинешь просто так

В Postman можно кидать запросы любой сложности + это гораздо удобнее (напр. можно шарить данные между запросами)


Общий язык с бекендом

С Postman можно проверить, что серв отдает нормальные данные, а так же проверить отдает ли он их вообще


Шаринг апишки, если нет Swagger

В Postman можно делать коллекции запросов и экспортировать в 1 json-файлик

Ну и как этим пользоваться?

На примере httpbin посмотрим как кидать запросики

Пару слов про httpbin

httpbin - это сервис, в который можно кидать любые http-запросы и видеть их содержимое

Вот он какой
Вот он какой

Вернемся к Postman

  1. Итак, качаем с офф-сайта, ставим + логинимся, видим начальный экран - он же Launchpad, жмем Create a request
Начальный экран
Начальный экран
  1. Появляется экран отправки запроса — тут все и происходит
Экран отправки запроса
Экран отправки запроса
  1. Кинем POST-запросик с какими-нибудь параметрами; для этого выбираем POST-метод, заполняем URL, и напишем какой-нить джсончик
Результат отправки
Результат отправки

В ответе видим, что отправили POST-запрос на https://httpbin.org/post с json-данными {"field": "value"}

  1. И, для закрепа, кинем еще GET-запрос с query-параметрами:
GET-запросик
GET-запросик

В ответе видим, что отправили GET-запрос на https://httpbin.org/get с query-параметрами field=value

К слову, запросики можно кидать как с json-данными, так и с query-параметрами, например, в query-параметрах отпрвляется токен, а в json-body остальные параметры запроса

Аутентификация

Обычно, чтобы кинуть какой-либо запрос, нужно аутентифицироваться/авторизоваться

Рассмотрим популярные способы аутентификации и как их проводить в Postman

Токен

Аутентификация с помощью токена (еще называется JWT-токен) - самая простая и понятная схема аутентификации

Схема состоит из двух этапов:

  1. Отправка запросика на аутентификацию, в который передается логин/апи-ключ/апи-секрет
  2. Получение токена из ответа запроса и передача его в другие запросы

Токен - это строка такого вида:

eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJKb2huIEdvbGQiLCJhZG1pbiI6dHJ1ZX0K.LIHjWCBORSWMEibq-tnT8ue_deUqZx1K0XxCOXZRrBI

Эту строку передаем в другие запросики как заголок или как параметр - тут как разраб решил

Authorization-заголовок

Передавать токен как Authorization-заголовок в Postman можно по-разному

  • Используя вкладку "Headers":
Токен как Authorization-хедер
Токен как Authorization-хедер
  • Используя вкладку "Authorization" и тип "API Key":
Вкладка Authorization + тип API Key
Вкладка Authorization + тип API Key
  • По науке передавать токен в такой схеме нужно используя префикс Bearer - для этого на той же вкладке выбираем тип "Bearer Token":
Вкладка Authorization + тип Bearer Token
Вкладка Authorization + тип Bearer Token

Query-параметр

Еще один способ передать токен - с помощью query-параметров. И тут опять есть несколько способов установки в Postman:

  • Используя вкладку "Params":
Токен как query-параметр
Токен как query-параметр
  • Используя вкладку "Authorization", тип "API Key" и настройку "Add to" = "Query Params":
Authorization + API Key + Add to Query Params
Authorization + API Key + Add to Query Params

Логин и пароль ака Basic Auth

Basic Auth - это когда сразу кидаем запросы, имея логин и пароль, не кидая при этом дополнительных запросов

Для проведения такой аутентификации, в Postman, выбираем вкладку "Authorization" и тип "Basic Auth":

Вводим доступы, видим что отправляется Authorization-хедер с зашифрованными BasicAuth-данными
Вводим доступы, видим что отправляется Authorization-хедер с зашифрованными BasicAuth-данными

Коллекции

Когда нужно кидать не один запрос и не один раз, хорошо бы завести коллекцию запросов

Так выглядят коллекции
Так выглядят коллекции

Коллекция - это по сути папочка с запросиками + плюшечки:

  • Папочки можно делать вложенными
  • Коллекцию/папочки/запросики можно именовать и документировать
  • Можно выставлять общие данные для запросов (напр. токен, айдишники какие-нибудь)
  • Можно делиться коллекциями с другими + импортировать коллекции других компаний, напр. Twitter, Notion, Slack
  • Коллекции синхронизируются на аккаунте - так что можно создать коллекцию на одном компе, войти на другом компе и увидеть все сохраненные коллекции
  • Можно импортнуть из других популярных форматов API, напр. OpenAPI/Swagger

Создание коллекции и добавление запросов

Коллекцию можно создать из панели сбоку, нажав на "Create collection"; или сохранив запрос, нажав кнопку "Save" или Ctrl + S, и создав коллекцию оттуда

Сохранение запроса с возможностью выбрать или создать коллекцию
Сохранение запроса с возможностью выбрать или создать коллекцию

Общие данные ака переменные

В окне редактирования коллекции (... > Edit) есть вкладка "Variables":

Вкладка Variables
Вкладка Variables

Здесь можно выставлять данные, которые будут использоваться всеми запросами коллекции, такими как токены, айдишники

Создание переменной
Создание переменной
  • Variable - это название переменной
  • Initial Value - можно оставить пустым
  • Current Value - значение переменной, которое будет отправляться вместе с запросом

Как использовать переменные

Для того чтобы использовать переменные юзаем такой синтаксис {{название-переменной}}

Эту штуку можно вставлять в любое место запроса: query-параметры, заголовки, json-body

Использование переменной в Authorization
Использование переменной в Authorization

Еще о переменных

Енвайронменты

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

В Postman для этого существует Environment (енвайронмент, енв) - это как раз тот самый набор переменных, которые можно быстро выставлять и переключать для всех запросов

Environment
Environment

Работает и настраивается все так же как и для коллекций, но приоритет у енвайронментов выше. Так что если выставить переменную token в коллекции и в енвайронменте, то значение будет взято из енва

Области видимости / приоритеты / уровни / scopes переменных

Вообще в постмане существует несколько уровней переменных:

Уровни переменных
Уровни переменных

Работают они от global до local, то есть как я писал про енвы, если выставить переменные на уровне collection, то совпадающие по названию переменные перезапишутся переменными из уровня environment

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

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

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

Чтобы каждый раз ручками не обновлять токен, нужно написать немножко кода, и в Postman как раз есть возможность запускать код после отправки запроса - вкладка "Tests"

Заходим в раздел "Tests" и у нас появляется возможность писать JavaScript-код:

Вкладка Tests, где можно писать код
Вкладка Tests, где можно писать код

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

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

const token = pm.response.json().token;
pm.collectionVariables.set("token", token);

В данном случае считаем, что в ответе на запрос приходит json такого вида:

{
  "token": "какой-то токен"
}

Мы читаем его и выставляем в переменные коллекции

Если нужно выставить в переменные енва, то пишем такое:

pm.environment.set("token", token);

Ссылочки

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

Я считаю, что Постмана за глаза хватает, и альтернативы не нужны, но в трендах Github часто возникают клоны Postman:

  • insomnia - опенсурсная альтернатива
  • hoppscotch (бывш. Postwoman) - браузерная альтернатива
  • httpie - клишная альтернатива
    • HTTP Prompt - надстройка над httpie, которая позволяет интерактивно собирать запросик
  • curl - самый старенький клишный кидатель запросиков, по-умолчанию стоит на Linux/Mac