Знакомство с Postman: кто ещё бывает клиентом
Что такое API и endpoint, почему клиент — не только браузер и зачем тестировщику Postman. А ещё: чем path-параметры отличаются от query-параметров и что есть в окне Postman.
О продукте
Привет! Есть новая задача. Команда переделывает каталог BB Food: сервер с новым API уже готов, а страницу каталога фронтенд-разработчики ещё делают. Проверить API нужно уже сейчас.
А как его проверить без страницы? Браузеру ведь нечего открыть.
Хороший вопрос! Запросы можно отправлять не только из браузера. Кадри покажет инструмент, которым тестировщики пользуются каждый день, — Postman.
Привет! Прежде чем открывать Postman, разберёмся со словами, которые ты теперь будешь слышать каждый день.
Алекс сказал, что API уже готов. А что такое API?
API (Application Programming Interface, программный интерфейс) — это способ, которым программы общаются друг с другом. Сервер заранее объявляет: «Вот какие запросы я понимаю, и вот что на них отвечу». Клиент может пользоваться только этим: внутрь сервера и в базу данных он не заглядывает.
Представь продуктовый магазин с прилавком. Покупатель не заходит за прилавок и на склад: он смотрит прайс-лист и просит нужный товар, а продавец принимает заказ и приносит товар со склада.
- API — это прилавок с прайс-листомСписок того, что можно попросить, и правила, как попросить.
- API — часть сервераПрилавок — не отдельное здание, а часть магазина. Так и API — не отдельная программа, а часть самого сервера: его «вход», через который сервер принимает запросы.
Работа тестировщика API — отправлять серверу запросы из этого списка и проверять ответы. Причём не только правильные запросы, но и с ошибками: с пустыми полями, неверными данными, без авторизации.
Проверим. Что такое API?
А ещё разработчики всё время говорят «endpoint». Это что?
Endpoint (эндпоинт, «конечная точка») — одна конкретная строчка этого прайс-листа: метод вместе с путём, по которому можно обратиться к серверу. Например, GET /api/v1/products — «получить список товаров».
Полный адрес запроса складывается из базового адреса сервера (base URL) и пути. Базовый адрес у всего API общий, а методы и пути у endpoint’ов разные.
GETметодhttps://bb-food.eebase URL/api/v1/productsпутьendpoint=GET+/api/v1/products
Все endpoint’ы с описанием обычно собраны в документации API, часто в Swagger. Обычно Swagger генерируется автоматически по коду бэкенда — той программы, которая работает на сервере. Поэтому в нём видно, что сервер умеет на самом деле. С него тестировщик и начинает. Вот как выглядит «прайс-лист» нашего каталога:
Один и тот же путь с разными методами — это разные endpoint’ы: GET /api/v1/products читает список, а POST /api/v1/products добавляет товар. Вместо {id} подставляют номер товара — к этому вернёмся чуть позже.
Сколько здесь разных endpoint’ов?
GET /api/v1/products
POST /api/v1/products
GET /api/v1/products/{id}Теперь про клиентов. В серии «Клиент-сервер» запросы к API всегда отправлял браузер. Поэтому легко решить, что клиент — это и есть браузер. Но это не так.
А кто ещё может быть клиентом?
Клиент — это любая программа, которая отправляет запрос серверу. Серверу всё равно, кто к нему обратился: он видит только сам запрос — метод, адрес, заголовки и тело — и отвечает на него.
Покупатель открывает каталог в браузере — клиент браузер. Открывает в мобильном приложении — клиент приложение.
Проверим. Браузер покупателя, мобильное приложение магазина и Postman у тестировщика отправляют запросы на наш сервер. Кто из них клиент?
А чем ответ в Postman отличается от того, что видно в браузере?
Сам ответ сервера тот же самый. Разница в том, как клиент его показывает.
Браузер берёт JSON и рисует из него страницу: карточки товаров, цены, кнопки. Postman ничего не рисует. Он показывает ответ как есть: код статуса, время, размер и сам JSON.
[
{"id": 1, "name": "Бананы, 1 кг", "price": 1.49},
{"id": 5, "name": "Ржаной хлеб", "price": 1.79}
]Тестировщику нужно и то и другое: Postman показывает, что ответил сервер, а браузер — что из этого увидел пользователь.
Браузер и Postman отправили на сервер одинаковые запросы GET /api/v1/products. Чем будут отличаться ответы?
А зачем тестировщику отправлять запросы мимо браузера?
Причин несколько:
- Не ждать интерфейс — API можно проверять, пока страницы ещё нет. Как раз наш случай.
- Найти, где баг — если в Postman ответ правильный, а на странице неправильный, ошибка на клиенте. Если неправильный уже в Postman, ошибка на сервере.
- Отправить то, чего не даст форма — пустое название, цену буквами, чужой id, запрос без токена. Сервер должен защищать себя сам, а не надеяться на форму.
- Работать быстрее — не нужно каждый раз проходить всю страницу, чтобы проверить одно действие.
Покупатель жалуется: в каталоге на сайте нет ржаного хлеба. Ты отправляешь GET /api/v1/products из Postman, и хлеб в ответе есть. Где искать баг?
Форма в админке не даёт ввести цену буквами. Значит, сервер точно не сохранит цену «abc»?
Слушай, в адресах мне попадались и /api/v1/products/5, и ?sort=price. Это одно и то же?
Хороший вопрос — давай немного углубимся в адрес запроса. Передать данные в адресе можно двумя способами.
Path-параметр — часть самого пути. В /api/v1/products/5 число 5 говорит, с каким именно товаром мы работаем. Мы уже встречали его в PATCH, PUT и DELETE. Без него адрес означает другое: /api/v1/products — это весь список.
Query-параметры пишут после знака ?: пары «ключ=значение», разделённые знаком &. Они не выбирают ресурс, а уточняют запрос: отфильтровать, отсортировать, ограничить количество. /api/v1/products?category=bread&sort=price значит «дай товары из категории хлеб, отсортированные по цене». Порядок query-параметров не важен, а часто их можно не указывать вовсе.
https://bb-food.eeадрес сервера/api/v1/products/путь5path-параметрhttps://bb-food.eeадрес сервера/api/v1/productsпуть?category=bread&sort=pricequery-параметрыПодсказка: path отвечает на вопрос «какой именно?» — конкретный товар, заказ, пользователь. Query отвечает на вопрос «какие и как?» — фильтр, сортировка, страница.
Нужно получить один товар — с id 7. Какой адрес правильный?
Покупатель выбрал в каталоге «только хлеб, сначала дешёвые». Как это скорее всего будет выглядеть в адресе?
Понятно! А что умеет Postman?
Давай посмотрим на его окно. Нажимай на любую часть — расскажу, что там. Значком «дальше» отмечено то, что подробно разберём в следующих блоках.
Осмотрено: 0 из 12
Выбери часть окна выше.
Строка запроса
Слева выбираешь метод: GET, POST, PUT, PATCH или DELETE. Справа пишешь адрес. Кнопка Send отправляет запрос — в этот момент Postman и становится клиентом.
Params
Таблица Query Params: впиши sort = price, и Postman сам допишет ?sort=price в конец адреса. А если написать в адресе /api/v1/products/:id, ниже появится таблица Path Variables — там задаёшь path-параметр, например id = 5.
Authorization
Здесь указывают, кто отправляет запрос: токен (Bearer Token), логин и пароль (Basic Auth) или ключ API. Убрал токен — и проверил, что сервер ответит 401.
Headers
Заголовки — служебная информация о запросе. Например, Content-Type: application/json говорит серверу, что в теле JSON. Многие заголовки Postman добавляет сам.
Body
Тело запроса для POST, PUT и PATCH. Чаще всего это JSON (raw → JSON), иногда форма с файлами (form-data). Здесь можно отправить что угодно — даже то, что форма на сайте не пропустит.
Scriptsдальше
Небольшие программы на JavaScript, которые запускаются до или после запроса. Например, сами проверяют, что код ответа 200, а в ответе есть нужное поле. Это первые шаги автоматизации.
Статус, время, размер
Код ответа (200 OK), за сколько миллисекунд ответил сервер и сколько весит ответ. Слишком медленный ответ — тоже повод для баг-репорта.
Тело ответа
То, что прислал сервер. Pretty — с отступами и подсветкой, Raw — как пришло, Preview — как показал бы браузер. Рядом вкладки с заголовками ответа и cookies.
Collections
Сохранённые запросы, разложенные по папкам: например, «Каталог», «Корзина», «Админка». Коллекцией можно поделиться с командой, и все будут проверять одно и то же.
Environments
Окружения и переменные. Вместо адреса пишешь {{baseUrl}}, а его значение зависит от окружения: тестовый сервер или рабочий. Переключил окружение — и все запросы уходят на другой сервер.
History
Все запросы, которые ты отправлял, даже несохранённые. Можно повторить вчерашнюю проверку в один клик.
Import, Runner, Mockдальше
Import загружает готовые запросы из описания API (OpenAPI, Swagger) или из команды cURL. Runner запускает всю коллекцию разом. Mock-сервер отвечает заглушками, пока настоящего API ещё нет.
Всё осмотрел, давай проверим!
Нужно добавить товар через POST. Куда в Postman вписать JSON нового товара?
Нужно проверить, что без входа в систему товар добавить нельзя. Где в Postman убрать токен?
Вчера ты проверял запрос, но забыл его сохранить. Где его найти?
Одни и те же запросы нужно отправлять то на тестовый сервер, то на рабочий. Как не переписывать адрес в каждом?
Отлично! Теперь ты знаешь, что Postman — такой же клиент, как браузер, и что где лежит в его окне. Дальше в этом блоке будем отправлять запросы сами: начнём с GET.
Справка по теме
API
Правила, по которым программы общаются: какие запросы понимает сервер и что он на них ответит. Как прилавок с прайс-листом в магазине: покупатель просит товар по прайс-листу и не ходит на склад, а клиент обращается к API и не ходит в базу данных.
Endpoint
Один конкретный пункт API: метод вместе с путём, например GET /api/v1/products. Полный адрес — это базовый адрес (base URL) плюс путь. Один путь с разными методами — это разные endpoint’ы. Все они описаны в документации API, часто в Swagger, который обычно генерируется автоматически по коду бэкенда.
Кто может быть клиентом
Клиент — любая программа, которая отправляет запрос серверу: браузер, мобильное приложение или Postman. Сервер видит только запрос и отвечает на одинаковые запросы одинаково.
Postman
Программа для отправки запросов к API вручную. Показывает ответ как есть: код статуса, время, размер, заголовки и тело. Браузер же рисует из ответа страницу.
Зачем тестировщику запросы мимо интерфейса
Проверить API, пока страницы ещё нет; понять, где баг — на клиенте или на сервере; отправить данные, которые форма не пропустит; быстрее повторять проверки.
Path- и query-параметры
Path-параметр — часть пути и выбирает конкретный ресурс: /api/v1/products/5. Query-параметры идут после ? парами ключ=значение через & и уточняют запрос: /api/v1/products?category=bread&sort=price.
Окно Postman
Строка запроса (метод, адрес, Send), вкладки Params, Authorization, Headers, Body и Scripts, панель ответа. Слева — коллекции, окружения и история.
Коллекции и окружения
Коллекция — сохранённые запросы по папкам, ими можно делиться с командой. Окружение хранит переменные, например {{baseUrl}}: переключил окружение — запросы ушли на другой сервер.