В мире, где статические веб-сайты и приложения все больше и больше зависят от отдельно поддерживаемых API, может быть сложно разобраться в том, как они работают, просто «поигравшись» с ними в веб-браузере.
Итак, чем же нам может помочь Postman в тестировании существующих API и понимании того, как они работают?
Что такое Postman?
Postman – это инструмент, который можно использовать для надежного тестирования API с помощью простых конфигураций. В него встроены функции, которые необходимы для работы с API, в том числе аутентификация, настройка заголовков, настройка полезной нагрузки и др.. Это помогает уменьшить количество конфликтом при использовании API.
Этот инструмент можно использовать не только для тестирования. Его преимущество в том, что разные члены команды могут использовать его для различных аспектов работы с API. Возможно, руководитель проекта хочет убедиться, что все работает, или ему, возможно, проще внести какие-то изменения напрямую через API, или QA-инженер хочет убедиться, что все по-прежнему работает, или разработчик хочет постоянно вносить изменения, работая при этом над самим API.
Самое лучшее - это, что Postman предоставляет функции для совместной работы. Бесплатная версия поддерживает экспорт и импорт коллекций сохраненных запросов API, а также создание общих ссылок. Если у вас есть команда, то есть и платная версия, которая позволяет синхронизировать коллекции для того, чтобы у всех была самая последняя и актуальная их версия.
Что мы собираемся делать/изучать?
Чтобы пробежаться по концепциям Postman, мы рассмотрим два примера API.
Для начала мы рассмотрим несколько простых HTTP-запросов с общедоступным API для Pokemon.
А затем воспользуемся API Yoda Translator для того, чтобы продемонстрировать, как выполнять определенные HTTP-запросы.
Как только мы разберем, как работают основы, мы воспользуемся API Lord of the Rings, чтобы узнать, как работает аутентификация с API. Для этого вам потребуется зарегистрировать бесплатную учетную запись, чтобы у вас был ключ API.
Часть 0: Настройка Postman
Пока мы не начали, вам нужно будет установить Postman для того, чтобы делать все вслед за этим руководством. Не может не радовать то, что есть бесплатная версия Postman для Mac, Windows и Linux, так что вы сможете найти подходящую вам версию.
Скачайте Postman: https://www.postman.com/downloads/
После того, как вы скачаете его, выполните стандартные инструкции по установке, откройте его, и вы готовы к работе!
Часть 1: Введение в Postman
Когда вы откроете Postman в первый раз, то перед вами сразу же появится панель запуска с большим количеством опций для работы.
Все это может показаться вам сложным, но давайте разберем некоторые ключевые понятия, которые вам нужно знать.
Запросы
Запрос – это именно то, на что и похоже, это конкретный API-запрос. Это будет запрос одного из двух типов: GET или POST, к определенной конечной точке. Вам нужно будет создавать новые запросы для каждого типа конечной точки. При тестировании это позволит вам перемещаться между ними.
Коллекции
Коллекция – это группа запросов. Удобно организовывать запросы в разные группы. Это могут быть два совершенно разных API (например, Twitter и Slack) или две разные группы API для одного API (например, API Twitter Tweets и API Twitter Accounts).
Авторизация
Авторизация – это то, как запросы аутентифицируются с помощью API. При этом неважно выполняет эти запросы человек или компьютер от вашего имени. Обычно для этого нужен ключ API. Это может быть статическое значение, которое было присвоено вашей учетной записи, или значение, которое было динамически сгенерировано с помощью таких инструментов, как OAuth.
Среды
Среды позволят вам настроить ваши конечные точки для того, чтобы вы могли использовать определенные переменные для из обозначения. Таким образом, вам будет проще использовать одни и те же конечные точки в разных средах. Например, у вас может быть одна и та же конечная точка /profile в эксплуатационной среде и в среде разработки, но с разными доменами. Среды позволяют управлять любым без исключения запросом с нефиксированным доменом.
Рабочие пространства
Мы не будем здесь слишком подробно говорить о рабочих пространствах, но вам нужно знать, что оно позволяет вам организовывать наборы коллекций и управлять ими. Если вы хотите использовать Postman как для работы, так и для личного проекта, то у вас может быть два рабочих пространства: Work и Personal соответственно.
В рамках этой статьи мы рассмотрим запросы, коллекции и авторизацию.
Часть 2: Создание нового запроса Postman для получения информации о Squirtle
Теперь, когда мы разобрались с терминологией, давайте создадим реальный запрос.
В левом верхнем углу пользовательского интерфейса вы должны увидеть оранжевую кнопку с надписью «New» (Создать). Нажмите на нее, а затем выберите «Request» (Запрос).
Перед тем, как мы перейдем к самому запросу, нужно указать несколько вещей.
Первое – это имя. Мы хотим начать с запроса информации о покемоне Squirtle, поэтому давайте назовем его «Pokemon - Squirtle».
Также нужно создать коллекцию, поэтому нажмите «Create Collection» (Создать коллекцию) и дайте ей имя «My Favorite Pokemon».
Нажмите на оранжевую кнопку с галочкой рядом с названием коллекции, а затем нажмите «Save» (Сохранить).
Теперь мы можем создать новый запрос, так что давайте сделаем это.
Для начала нужно заполнить пару полей для нашего первого запроса:
- Тип запроса: GET, POST, PUT и т.д. – мы будем использовать GET
- URL запроса: конечная точка для вашего API-запроса – мы будем использовать https://pokeapi.co/api/v2/pokemon/squirtle/
И как только вы их проверите и убедитесь в их правильности, можете нажать синюю кнопку «Send» (Отправить). Мы успешно создали наш первый запрос!
Мы увидим следующее:
- Body (тело): внизу мы должны увидеть тело ответа на API-запрос. Для нашего API Squirtle у нас должен появиться объект JSON со следующими данными: abilities, base_experience и forms.
- Status (статус): справа должен появиться код состояния HTTP. «200 Ok» - хороший признак – все прошло успешно!
- Time (время): количество времени, которое потребовалось на то, чтобы выполнить запрос.
- Size (размер): размер данных, полученных в ответе, в Кб (в нашем примере).
Вы можете навести курсор на Status, Time и Size, и получить более подробную информацию по каждому параметру.
Итак, мы сделали наш первый запрос!
Прежде чем мы пойдем дальше, заметим, что наш запрос выглядит так, как будто он находится во вкладке браузера. Если мы закончили работу с этим запросом, то мы можем просто закрыть вкладку и нажать «Save», чтобы убедиться, что все изменения внесены!
Часть 3: Создание коллекции запросов в Postman для PokeAPI
Теперь, когда мы создали запрос, давайте создадим коллекцию. Формально мы уже создали коллекцию еще в Части 2, но мы создадим здесь новую коллекцию, для того, чтобы узнать, как они работают.
В левом верхнем углу пользовательского интерфейса снова нажмите оранжевую кнопку «New» и выберите «Collection» (Коллекция).
Как и в случае с запросом, нужно ввести имя. Давайте назовем его «PokeAPI». Дополнительно вы можете добавить описание. После того, как вы заполните все поля, нажмите кнопку «Create» (Создать).
Слева у вас появится ваша коллекция. Вы можете выбрать и развернуть папку, поскольку мы с ней все равно будем работать.
Прежде чем мы добавим запрос, учтем тот факт, что PokeAPI имеет различные типы запросов, и организуем коллекцию еще более детально. Итак, давайте нажмем на три точки рядом с коллекцией PokeAPI и выберем «Add Folder» (Добавить папку).
Здесь снова нужно ввести имя. Папки – это своего рода коллекции внутри коллекции, поэтому параметры у них такие же. Давайте назовем ее «Pokemon» и нажмем, как м в предыдущих случаях, оранжевую кнопку «Save».
А теперь давайте добавим наши запросы! Для начала нажмите на три точки рядом с папкой Pokemon, как мы это делали при добавлении папки в коллекцию, но на этот раз выберите «Add Request» (Добавить запрос).
Давайте назовем этот запрос «Pokemon». У нас есть запрос Pokemon внутри папки с таким же именем, и это может путать, но Pokemon – это всего лишь одна из конечных точек группы Pokemon.
А теперь давайте воспользуемся тем же API, который мы использовали с нашим запросом Squirtle до этого:
- Тип запроса: GET
- URL запроса: https://pokeapi.co/api/v2/pokemon/squirtle/
И, как и в прошлый раз, нажав синюю кнопку «Send», мы должны увидеть ответ на запрос, который был успешно выполнен!
Теперь давайте добавим еще один запрос. Чтобы создать новый запрос в папке Pokemon PokeAPI, выполните все те же действия, что и до этого, и назовите этот запрос «Abilities».
Если вы пролистаете ответ от первой конечной точки Squirtle, то увидите большое количество других URL-адресов API. Сверху у нас есть abilities (способности), и их две – «torrent» и «rain-dish».
Выберите понравившуюся вам способность Squirtle и скопируйте соответствующий url в новый запрос Abilities, который мы с вами только что создали. Я выбираю rain-dish.
Мы можем не менять тип запроса – оставить GET, и нажать синюю кнопку «Send», и мы снова увидим ответ на успешно выполненный запрос!
И мы получаем дополнительную информацию о способности Squirtle под названием Rain-Dish, при этом некоторая информация приводится на разных языках, и это очень круто!
Итак, у нас теперь есть новая коллекция PokeAPI с папкой Pokemon, которая представляет собой группу конечных точек Pokemon API, в том числе Pokemon и Abilities.
На этих двух запросах мы закончим Часть 3, но вы можете смело добавить столько запросов PokeAPI, сколько захотите!
Часть 4: Выполнение POST-запросов с помощью Postman для преобразования предложений, как если бы их произносил Йода
До этого момента мы занимались только GET-запросами, но что делать, если нам нужен POST-запрос, в котором нам нужно отправить некоторые данные?
Для того, чтобы отправить POST-запрос, воспользуемся API Yoda Translator с сайта funtranslations.com. Несмотря на то, что этот API принимает только один параметр, он все еще является отличной общедоступной конечной точкой, которой мы можем воспользоваться для того, чтобы понять концепцию POST-запроса.
Во-первых, давайте создадим новую коллекцию с новым запросом:
- Коллекция: Fun Translations
- Запрос: Yoda
Но на этот раз, так как у нас уже не GET-запрос, наша конфигурация запроса будет следующей:
- Тип запроса: POST
- URL запроса: https://api.funtranslations.com/translate/yoda
Теперь, в данном случае, если мы нажмем на синюю кнопку «Send», то запрос не выполнится успешно с кодом 200, мы получим код 400!
На самом деле, все дело в том, что мы не настраивали никакие данные для отправки в API, а они нужны, так что давайте добавим их.
Прямо под URL-адресом запроса нажмите «Body» (Тело). А затем в качестве типа тела выберите raw вместо none. И наконец, справа от типов измените Text на JSON.
Далее в область под ним вы можете добавить следующее:
{
"text": "Hello, I am learning how to test APIs with Postman!"
}И теперь, снова нажмите синюю кнопку «Send». Запрос выполнился успешно, и вы получили ответ!
Эту концепцию мы можем применить практически к любому API. Postman позволяет отправлять данные не только в формате JSON, но и в других форматах, которые можно увидеть в разделе «Body Type», а это значит, что у вас есть большое количество вариантов, которые вы можете применять в зависимости от того, что требует используемый вами API.
Часть 5: Аутентификация запроса к API Lord of Rings с помощью ключа API
В последней части этого руководства мы будем использовать API Lord of Rings.
Начнем с того, что для того, чтобы отправлять запросы с ключом API к API Lord of Rings, нам нужно пройти аутентификацию. Итак, для начала, прежде чем мы с головой уйдем в эту тему, вам необходимо создать бесплатную учетную запись.
https://the-one-api.herokuapp.com/sign-up
Как только вы зарегистрируетесь и войдете в систему, первым, что вы увидите, будет ваш ключ API! Этот ключ нужно либо скопировать, либо запомнить, чтобы иметь возможность воспользоваться им позже. Если вы уйдете со страницы, то вы всегда сможете вернуться к ней. Вам нужно будет простой перейти к экрану приветствия Welcome, а затем к учетной записи через поиск веб-сайта API.
Для начала давайте создадим новую коллекцию и запрос:
- Коллекция: Lord of Rings
- Папка: Movie
- Запрос: All Movies
- Тип запроса: GET
- URL запроса: https://the-one-api.herokuapp.com/v1/movie
После того, как вы настроите все, что указано выше, нажмите кнопку «Send», и вы сразу же получите ответ с кодом 401, который говорит о том, что вы не прошли аутентификацию.
Так как для данного API необходим ключ API, то это именно то, что мы и ожидали получить. Итак, давайте нажмем на вкладку «Authorization» (Авторизация). Там мы можем выбрать значение Bearer Token (Токен носителя) для Type (Тип) и справа вставить ваш ключ, который вы только что настроили с помощью API Lord of Rings.
И как только вы нажмете на кнопку «Send», вы получите ответ на успешно выполненный запрос!
В данном случае все сработало отлично, но что, если у нас будет большое количество запросов, которые будут использовать один и тот же ключ? Должны ли мы это как-то регулировать при каждом запросе?
Вместо того, чтобы регулировать это для каждого запроса, мы можем это делать внутри коллекции. Давайте сначала создадим еще один запрос.
В нашей коллекции Lord of Rings, в папке Movies, создайте новый запрос:
- Запрос: Quote by Movie ID
- Тип запроса: GET
- URL запроса: https://the-one-api.herokuapp.com/v1/movie/{id}
Давайте в этом запросе воспользуемся ID из ответа на первый запрос. Я буду использовать 5cd95395de30eff6ebccde5b, который является ID для The Two Towers, поэтому URL запроса будет выглядеть следующим образом:
https://the-one-api.herokuapp.com/v1/movie/5cd95395de30eff6ebccde5b
Теперь, вместо того, чтобы настраивать наш токен в разделе Authorization нашего запроса, мы оставим тип Inherit auth from parent (Наследование авторизации от родителя). Нажмите на три точки рядом с коллекцией и выберите «Edit» (Редактировать).
Здесь мы будем делать то же самое, что и с первым запросом, но уже с Collection. Выберите вкладку Authorization, в качестве типа выберите Bearer Token и в поле Token снова вставьте свой токен.
И в конце, нажмите «Update» (Обновить) и снова нажмите синюю кнопку «Send», и вы увидите, что запрос выполнился успешно!
Теперь мы можем вернуться к нашему запросу All Movies и обновить данные во вкладке Authorization, чтобы использовать тип Inherit auth from parent, и все должно продолжить работать!
Что еще можно делать с помощью Postman?
Несмотря на то, что я рассмотрел достаточно много всего, у Postman гораздо больше возможностей. Вот несколько моих любимых.
Переменные окружения
Если вы работаете над проектом в качестве разработчика, то очень вероятно, что ваша команда использует несколько различных сред, например, среду разработки и промышленной эксплуатации. Вместо того, чтобы создавать и обслуживать совершенно отдельные запросы, мы можете добавить переменную среды и менять ее, когда переключаетесь между средами!
Импорт и экспорт коллекций и данных
Отличительная особенность Postman заключается в том, что после того, как вы организовали свои запросы, вы можете их экспортировать для того, чтобы их могли использовать и другие. А значит, вы можете импортировать коллекции других членов команды. Таким образом можно легко убедиться в том, что все используют одну и ту же коллекцию.
Бонус: вы даже можете хранить эти файлы в репозитории Git, так как это просто файлы JSON.
Но не стоит забывать, что если вы используете в коллекции авторизацию, как было рассмотрено выше, то вам необходимо убедиться, что вы не добавили ее, когда экспортировали свою коллекцию.
Автоматизированное тестирование
Если у вас есть набор запросов в коллекции или, что еще лучше, если они хранятся у вас в GitHub, то вы можете использовать эти запросы как часть способа управления автоматическим тестированием вашего API.
Для этого есть несколько решений: в Postman есть средство запуска коллекций, которое встроено прямо в приложение, а Newman – это инструмент командной строки, который позволяет запускать тесты непосредственно из терминала.
