Программные интерфейсы

спринт Программные интерфейсы
Компьютерная сеть и протоколы
6/6
О чём этот спринт
Сетевая модель OSI
Сетевая модель TCP/IP
HTTP-запрос
Параметры HTTP-запроса
HTTP-ответ
Стили представления данных
2/2
JSON
XML
Postman
2/2
Postman: основная функциональность
Postman: тестирование API
Стили взаимодействия
4/4
Проектирование взаимодействия
1/1
Воркшоп и домашнее задание
1/2
Заключение
1/1
Спринт 13/18: Программные интерфейсы → Тема 3/7: Postman → Урок 1/2

Postman: основная функциональность

Айгуль
Ну всё, совсем скоро будешь отправлять запросы с помощью Postman.
Даня
А что это?
Айгуль
Postman — это программа, которая помогает отправлять HTTP- и HTTPS-запросы и получать ответы.
Даня
Ого!
Айгуль
Сейчас расскажу, как в Postman создавать запрос, добавлять параметры, работать с заголовками и телом запроса.
В этом уроке вы научитесь проверять работу API, отправляя запросы к нему в программе Postman.
Сначала Postman нужно скачать и установить — для этого перейдите по ссылке.
Запустите приложение. Перед вами главный экран, который делится на две части:
  • слева — список сохранённых запросов и история изменений.
  • справа — область работы с запросами. Тут можно создавать запросы и настраивать их.
Обратите внимание: интерфейс может немного отличаться в зависимости от операционной системы устройства и версии приложения, но функциональность остаётся та же.
Чтобы создать запрос, нажмите на кнопку в виде плюса.
Перед вами окно работы с запросом. В нём вы можете:
  • выбрать метод запроса;
  • добавить и отредактировать URL, по которому нужно отправить запрос;
  • задать параметры запроса;
  • добавить запросу заголовки;
  • составить тело запроса.

Как выбрать метод запроса

Посмотрите на URL. Найдите выпадающий список слева от него: по умолчанию в нём указан метод GET.
Если нажмёте на выпадающий список, увидите все методы HTTP-запросов. В работе вы чаще всего будете использовать GET, POST, PUT, DELETE.
Не забывайте проверять, какой метод указываете. По умолчанию новые запросы создаются с GET, и можно забыть поменять его на нужный метод.
Если указать неправильный метод, вернётся ошибка.

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

В URL можно передавать параметры запроса. Они позволяют уточнить, какие именно данные нужно передать.
Параметры запроса перечисляются в URL после знака ? в виде ключ=значение. Если параметров запроса несколько, то они разделяются знаком &.
Формат записи: URL?ключ=значение&ключ=значение&….
Например, запрос [clothing.com](http://clothing.com)?type=sweatshirt&color=white следует читать так:
  1. clothing.com — URL.
  2. Символ ? указывает на то, что далее идут параметры запроса.
  3. type=sweatshirt — первый параметр запроса «тип=свитшот».
  4. Символ & разделяет разные параметры запроса.
  5. color=white — второй параметр запроса «цвет белый».
Добавлять и редактировать параметры в Postman можно во вкладке Params.
Укажите KEY (ключ) и VALUE (значение) параметра. Например, нужно задать цвет кота. Тогда KEY — cat, VALUE — BLUE.
Параметры автоматически подставятся в URL. Задайте параметр cat=BLUE и посмотрите на URL: он появился в запросе после вопросительного знака.
Напротив каждого параметра стоит чек-бокс. Если поставить там галочку, параметр добавится в URL. Если отключить — исчезнет.
Например, добавлено два параметра: цвет кота — голубой и белый. Голубой отключён — его нет в URL. Белый активный — он стоит в URL после вопросительного знака.
Есть ещё один способ добавить параметр — с помощью кнопки Bulk Edit («Массовое редактирование»). Она находится во вкладке Query Params — справа.
Этот режим напоминает блокнот: нужно записать все параметры в столбик в формате key:VALUE. Например, так: cat:BLUE.
Если нужно отключить один из параметров — достаточно поставить перед ним два слеша (//key:VALUE):
Пока что для ваших задач не будет разницы между режимами. Используйте тот, который вам удобнее.

Как задать заголовок запроса

Вы уже знаете из предыдущих уроков, что заголовки — это дополнительная техническая информация, которая передаётся от клиента к серверу. Например, тип браузера или длина контента в байтах.
В Postman заголовки можно задавать вручную на вкладке Headers. Но некоторые заголовки могут проставляться автоматически. Например, Host — для имени домена, Content-type — для формата данных. Эти заголовки по умолчанию скрыты. Чтобы их увидеть и при необходимости отредактировать, нужно кликнуть на кнопку «Hidden».
Заголовки можно отключать и включать — с помощью чекбокса. Это пригодится, чтобы проверить, как ведёт себя API, если какого-то заголовка нет.
Подробнее про заголовки — в документации к Postman.

Как задать тело запроса

В теле указывают данные, которые нужно отправить в запросе — чаще всего для создания и редактирования объекта. Например, такое тело описывает объект «кошка» с именем Daisy рыжего цвета:
JSON
{ 
  "animal_type": "сat",
    "name": "Daisy", 
    "color": "ginger" 
}
Для создания кошки будет использоваться метод POST.
Тело задаётся во вкладке Body. Здесь нужно выбрать, в каком формате его отправить на сервер: none, form-data и другие.
Пока что вам пригодится только формат raw. Он означает, что данные в запросе будут переданы так, как вы их напишете. Внутри raw можно выбрать:
  • Text,
  • JavaScript,
  • JSON,
  • HTML,
  • XML.
Указывайте тот формат, который умеет читать сервер. Это можно узнать из документации к приложению или у разработчика.
Обязательно убедитесь, что выбран правильный формат данных. В raw по умолчанию указан Text. Если сервер ожидает JSON, а запрос придёт в другом формате, вернётся ошибка.
Итак, удалось указать:
  • метод запроса;
  • URL, куда отправлять запрос;
  • тело и параметры — если они нужны.
Теперь можно отправить запрос.

Как отправить запрос

Нужно нажать кнопку Send.
После этого от сервера придёт ответ. Он появится в нижней части экрана на вкладке Body.
На картинке URL написан для примера: его вводить не нужно. С рабочим URL вы попрактикуетесь дальше.
На вкладке Body можно настроить, как именно вы хотите прочитать ответ:
  • Pretty — позволяет посмотреть тело ответа так, чтобы было удобно читать: с подсветкой элементов и отступами;
  • Raw — ответ будет в «сыром» виде: без отступов и подсветки элементов;
  • Preview — показывает результат: например, если ответ — страница сайта, можно посмотреть, как она выглядит.
  • Visualize — позволяет преобразовать данные в график или таблицу.
Также здесь можно увидеть код ответа, куки, заголовки и другую полезную информацию. Можно сохранить ответ на компьютер.

Как задать окружение

Одна из задач системного аналитика — тестировать API, то есть отправлять запросы и проверять полученный ответ.
Системный аналитик может работать с разными версиями одного и того же API. Например, с версией, которую дорабатывает команда разработки (dev, от слова development), и с той, которая доступна пользователям (prod, от слова production). Также в проекте может участвовать несколько сервисов, у каждого из которых будет свой API.
Такой API может иметь набор переменных с фиксированными значениями. Чтобы не прописывать эти повторяющиеся переменные в каждом запросе, команда разработки может использовать в Postman окружения. Окружение — это набор переменных, которые используются при выполнении запросов.
Например, для доступа к API запрос должен содержать логин и пароль. Для версии dev API будет использоваться одна пара логина и пароля, а для версии prod API — другая. Чтобы не вводить эти данные при каждом запросе, можно просто указать окружение.
Настроить окружения можно в разделе Environment. Если команда разработки использует разные окружения, то переменные и их значения для каждого окружения нужно запросить у разработчика.
При выполнении запросов обращайте внимание на окружение, в котором этот запрос выполняется. Окружение указывается в области над кнопкой «Send». По умолчанию указывается «No Environment». Доступные окружения можно выбрать в выпадающем списке.
Создайте и отправьте свой первый запрос с помощью Postman:
  1. Выберите метод запроса — GET.
  2. В адресной строке укажите URL — google.com.
  3. Нажмите Send, чтобы отправить запрос.
    Посмотрите на ответ в нижней части экрана: выберите Body → Preview. Отметьте результат.
Должно получиться так:
Теперь потренируйтесь отправлять запросы в API Яндекс Прилавка, которое разработчики передали вам на тестирование. Это приложение для заказа продуктов с быстрой доставкой.
Посмотрите в требования. Найдите блок «Работа со складом». В нём сказано, что в приложении есть четыре складских отделения, и ниже таблица со складами:
  • «Имеется всё»,
  • «Чердак»,
  • «Большой мир»,
  • «Шведский дом».
Отправьте запрос, который вернёт в ответе список складов, а заодно сравните список складов из ответа со списком из требований.
Для этого найдите в тех же требованиях URL, на который нужно отправить запрос. Загляните в блок «Требования к URL». Там указано: должен присутствовать URL, который возвращает список складов: GET /api/v1/warehouses.
Теперь нужно:
  • отправить запрос на указанный URL. Параметры указывать не нужно: про них ничего не сказано в требованиях;
  • получить ответ со списком складов;
  • сравнить список складов в ответе со списком из требований.
Изучите в методичке , как запускать сервер с API Яндекс Прилавка.
Нажмите кнопку «Запустить сервер». У вас появится ссылка — она начнёт работать не сразу. Придётся подождать около минуты.
Запустите Postman и создайте запрос:
  1. Выберите метод GET.
  2. В адресную строку скопируйте адрес сервера и добавьте URL, по которому нужно обратиться, чтобы получить список складов. Вы его уже знаете — /api/v1/warehouses. В адресе запроса должен получиться URL вида: https://42b6da57-454e-4a3e-874f-5c73794df4e4.serverhub.praktikum-services.ru/api/v1/warehouses. Не забудьте поменять адрес сервера на тот, что у вас.
  3. Нажмите Send.
Обратите внимание: если увидите статус Try to deploy server first или ошибки 403 Forbidden и 404 Not Found, вернитесь к методичке — здесь есть ответы на многие вопросы.
Отметьте результат, который получился в ответе:
Проверьте, совпадает ли список складов с ожидаемым результатом: он такой же, как указано в требованиях?