API — Тестирование API c Postman

• Создание API
• Интеграция с GitHub
• Работа с API
• Отправка сделанных изменений

В современной разработке API документирование играет важную роль. Хорошая документация помогает другим разработчикам понять, как работает ваше API и упрощает процесс интеграции с вашим сервисом.

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

Представьте, что вы работаете над проектом в команде и у вас уже есть описание API в формате OpenAPI. Как же использовать это описание в Postman для выполнения запросов к эндпоинтам, не перенося данные вручную? Тут еще возникает вопрос синхронизации, как переносить изменения, сделанные в спецификации, в коллекции запросов в Postman. Для решения этой задачи в Postman есть специльный инструмент — API Builder и в этом уроке мы поговорим о нем

API Builder — это мощный инструмент в Postman. Он позволяет создавать новый или импортировать уже существующий API, описанный в формате OpenAPI, а затем генерировать коллекцию запросов, которые затем можно прямо здесь и выполнить.

Одной из ключевых особенностей API Builder является его интеграция с GitHub. Благодаря этой интеграции, можно связать спецификацию API с репозиторием на GitHub. Это позволяет управлять версиями API, отслеживать изменения, а также сотрудничать с другими разработчиками в режиме реального времени.

Верхнеуровнево процесс работы с API в Postman может выглядеть так:

• Создание API или импорт уже существующего
• Подключение git-репозитория, чтобы синхронизировать изменения между Postman и удаленным git-репозиторием
• Непосредственно работа с API. Выполняйте запросы, при необходимости редактируйте определение API
• Отправка сделанных изменений в Git репозиторий. Также периодически нужно стягивать данные из удаленного репозитория, чтобы получить изменения, сделанные другими разработчиками в определении API

Теперь рассмотрим каждый из этапов более подробно

Создание API

API Builder позволяет нам создавать новые API с нуля или импортировать уже существующие, описанные в OpenAPI формате. Мы рассмотрим процесс импорта уже существующего API с GitHub

• Выберите «Импорт» на боковой панели

• Выберите Other Sources, а затем выберите GitHub

  Откроется вкладка браузера с просьбой войти в свой репозиторий в GitHub. Следуйте инструкциям на экране. Когда вы закончите, закройте вкладку браузера и вернитесь в Postman.

• В Postman выберите свой профиль и репозиторий, из которого вы хотите импортировать API. Затем выберите ветку с данными, которые вы хотите импортировать и нажмите Continue

• Выберите параметр, как импортировать. Мы будем импортировать API целиком вместе с коллекцией запросов

• Для завершения нажмите Import и дождитесь окончания процесса

Интеграция с GitHub

Интеграция API в Postman с GitHub обеспечивает контроль версий, что позволяет отслеживать изменения в API и коллекциях и при необходимости откатываться к предыдущим версиям. Кроме того, такая интеграция упрощает совместную работу в команде, позволяя нескольким разработчикам вносить изменения и обсуждать их через pull request

Так как интеграция с GitHub в Postman подразумевает командную работу, для активации этой функции необходимо создать или присоединиться к команде. Сделать это можно по инструкции

После создания команды приступим непосредственно к интеграции

• Нажмите API на боковой панели и выберите свой интерфейс

  

• В разделе Connect repository репозиторий выберите Connect и выберите тип репозитория, к которому вы хотите подключиться. В нашем случае это GitHub

  Откроется вкладка браузера с просьбой войти в свой репозиторий. Следуйте инструкциям на экране. Когда вы закончите, закройте вкладку браузера и вернитесь в Postman.

• На странице "Connect your repository" введите организацию и репозиторий, в котором будет храниться API

• Выберите ветку для API. Любые изменения, которые вы вносите в Postman, сохраняются в активной ветке

• Выберите каталог, в котором будут храниться коллекции. Этот пункт необязательный, по умолчанию для этого будет создан каталог postman/collections. Если вас это устраивает, оставьте поле пустым или задайте свой каталог

  

• Нажмите Connect Repository для завершения процесса

Работа с API

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

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

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

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

Отправка сделанных изменений

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

Для работы с Git используется панель Source Control. Для примера рассмотрим, как отправить сделанные изменения в привязанный репозиторий

• Выберите значок управления версиями на правой боковой панели.
• Введите сообщение с описанием сделанных изменений
• Нажмите Commit and Push, чтобы отправить сделанные изменения в репозиторий

В этом уроке мы научились работать с API в Postman. Мы узнали, как импортировать определение API на основе OpenAPI документации и автоматически создать коллекцию со всеми запросами этого API. Теперь вы можете отправлять запросы к вашему API и изучать ответы, не создавая запросы вручную. Кроме того, мы научились синхронизировать изменения в схеме API с коллекцией и отправлять все изменения во внешний репозиторий

Самостоятельная работа

В этом задании мы импортируем API веб-приложения, с которым работали ранее.

1. Создайте в своем профиле на GitHub новый репозиторий hexlet-postman. В нем будет находиться описание API в формате OpenAPI. Создайте в нем файл index.json с документацией. Саму документацию нашего приложения в формате OpenAPI можно взять тут
2. Выполните шаги из урока, импортируйте себе API, указав свой репозиторий в качестве источника
3. Выполните несколько запросов к эндпоинтам. Внесите какие-нибудь изменения в документацию, синхронизируйте их с коллекцией и сделайте пуш изменений в свой репозиторий

Дополнительные материалы

1. Создание и работа с API
2. Спецификация OpenAPI