Postman помогает компаниям проектировать, документировать, разрабатывать и тестировать API. Нам в команде МТС Exolve тоже. В этой статье рассмотрим, как использовать Postman для синхронизации и публикации обновлений с помощью его инструментов и API, которые облегчают управление жизненным циклом разработки.
Создание API, как и любого другого программного продукта, не обходится без подключения системы контроля версий. С её помощью над одним проектом, не мешая друг другу, может работать целая команда разработчиков, а сам продукт тестируют, добавляют новую функциональность и при необходимости откатывают изменения к первоначальному состоянию.
В конце, по готовности, вы сможете опубликовать свой API, чтобы пользователи прочитали документацию и просмотрели код. Однако обновление документации вместе с кодом обычно требует времени и усилий. Postman постепенно упрощает этот процесс, поэтому на основе их гайда мы решили сделать свой и затронуть GitHub Actions.
Управление версиями API с помощью Postman
Когда вы постите очередной вариант своего API в Postman, он становится доступным для его потребителей, и все ресурсы проекта на этом этапе будут включены в новую неизменяемую версию.
Используйте Semantic Versioning 2.0.0 для управления номерами версий, благодаря чему пользователи заранее будут знать, какие изменения произошли в новой версии. Например, исправления мелких ошибок или критические изменения всего проекта.
При помощи Postman вы сможете не только вручную опубликовать новую версию программы, но и автоматизировать этот процесс благодаря API. Для обновления содержимого API и публикации новых версий используйте эти endpoints:
POST https://api.getpostman.com/apis?workspaceId={{workspaceId}} — создать API.
PUT https://api.getpostman.com/apis/{{apiId}}/schemas/{{schemaId}}/files/{{filePath}} — создать или изменить содержимое корневого файла index.json API. Это запрос, который получает строковое содержимое JSON-файла, переданного в теле запроса.
POST https://api.getpostman.com/apis/{{apiId}}/versions — создать версию. Эта endpoint получает имя, примечания к выпуску и схему API для создания новой неизменяемой версии.
Создайте версию API с помощью API Postman
Чтобы создать новую API-версию с помощью Postman API, необходимо:
Получить новую версию определения при помощи формата спецификаций OpenAPI (Swagger).
Использовать нужный endpoint, чтобы создать или обновить файл схемы. Например, обновить несколько файлов, если API использует формат multi-file.
После внесения изменений вы сможете опубликовать новую версию, используя endpoint для её создания. В теле запроса укажите номер семантической версии и примечания к выпуску. Этот запрос возвращает информацию о новой версии, включая её идентификатор.
Запросы можно выполнить разными способами:
Использовать бекэнд-фреймворки (например, Axios с Node.js или Requests с Python).
Создать и вручную запустить коллекцию Postman.
Создать коллекцию и запустить её с помощью интерфейса командной строки Postman.
Созданный в Postman GitHub action упрощает процесс и позволяет запустить создание версии прямо из вашего репозитория.
Интеграция Postman c GitHub
GitHub Actions — это служба CI/CD, интегрированная с GitHub и используемая программистами для разработки, тестирования и развёртывания различных кодовых конструкций в GitHub.
Для настройки интеграции с GitHub Actions создайте конвейер в GitHub, а затем настройте свою API в Postman. После этого вы сможете просматривать статус сборок в Postman. Ранее на примере МТС Exolve также пробовали Actions для кейса отправки SMS.
Создание конвейера в GitHub
Чтобы построить конвейер в используемом для вашей API GitHub-репозитории, создайте в нём каталог с именем .github/workflows, а затем добавьте файл YAML (в нём будет определён конвейер). Дополнительные сведения смотрите в документации GitHub Actions.
Настройка интеграции GitHub Actions
Откройте свой API, выбрав его на боковой панели. Каждый API может быть связан с одним CI-проектом.
Перейдите в Test and Automation → Automate → Github Actions.
При желании дайте Postman доступ к вашей учётной записи GitHub. После этого вы можете закрыть вкладку браузера и вернуться в Postman.
GitHub устанавливает ограничение в десять токенов аутентификации на пользователя для каждого приложения. Если вы создадите более десяти подключений с одним и тем же пользователем, дополнительные токены будут отозваны в том порядке, в котором они были созданы.
Введите название, которое позже поможет распознать интеграцию. Postman заполняет никнейм в формате GitHub-{API_NAME}, и при желании вы можете его отредактировать.
Выберите GitHub organization с вашим репозиторием API.
Выберите сам репозиторий.
Нажмите Connect.
Просмотр статуса сборки
После настройки интеграции GitHub Actions вся информация о задании сборки (ветка, время начала и статус) станет доступна в Postman. Также можно просмотреть результаты запусков сбора данных, настроенных в вашем конвейере, с помощью Postman CLI.
Публикация новой версии API с помощью GitHub Actions
Прежде чем приступить к публикации, понадобится:
Действительный ключ API Postman.
Метод обновления и синхронизации определения API с вашим кодом, например его поддержка вручную.
Определение API в формате JSON в рабочей области Postman.
Идентификатор API. Чтобы получить его, найдите свою API, выберите значок информации и скопируйте идентификатор:
Использование GitHub Action
Код GitHub Action доступен в репозитории push-openapi-to-postman. Ниже приведён пример ручного триггера Action — Sync OpenAPI with Postman:
name: Sync OpenAPI with Postman
on:
workflow_dispatch:
inputs:
versionName:
description: 'The new version name'
required: true
default: '1.0.0'
releaseNotes:
description: 'The new version release notes'
required: false
default: ''
jobs:
sync-with-postman-api:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Push OpenAPI to Postman
id: pushApi
uses: postmanlabs/push-openapi-to-postman@v1
with:
path-to-definition: ./api-definition.json
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
api-id: ${{ vars.API_ID }}
api-path-to-file-name: index.json
version-name: ${{ github.event.inputs.versionName }}
release-notes: ${{ github.event.inputs.releaseNotes }}Здесь Action запрашивает у пользователя следующие github.event.inputs параметры:
VersionName: номер или имя версии, которое можно найти в списке версий вашей API.
ReleaseNotes: дополнительная информация, сообщающая пользователям об изменениях версии, например о том, что было удалено или добавлено.
При создании GitHub Action необходимо убедиться, что:
Определение API находится в формате JSON.
Path-to-definition указывает на файл определения в вашем репозитории GitHub.
Имя файла, которое вы обновляете в своём определении, соответствует значению в api-path-to-file-name входных данных. По умолчанию Postman использует имя индексного файла при создании API с помощью API Builder.
Настройка и запуск
Теперь, когда у нас есть всё необходимое, давайте настроим и запустим GitHub Action.
Шаг 1. Настройте репозиторий GitHub.
1.1. Создайте рабочий процесс, имя файла должно подсказывать его действия.
В примере мы будем использовать имя файла sync-with-postman.yml.
В репозитории создайте файл sync-with-postman.yml в папке .github/workflows.
Начать рабочий процесс можно, кликнув на вкладке GitHub Actions → New workflow → Simple workflow → Configure. Обновите имя файла и код GitHub Action.
1.2. Настройте переменные среды.
Внутри репозитория перейдите в Settings → Secrets and variables → Actions:
Во вкладке Variables создайте API_ID, переменную репозитория, содержащую идентификатор API, который мы хотим поддерживать в актуальном состоянии.
Перейдя в Secrets, создайте POSTMAN_API_KEY (repository secret), который содержит действительный ключ API Postman.
Зафиксируйте изменения соответствующей командой Git.
Шаг 2. Выполните GitHub Action.
2.1. Выберите вкладку Actions в своём GitHub-репозитории:
2.2. Выберите созданный вами action Sync OpenAPI with Postman:
2.3. Перейдите в пункт «Запустить рабочий процесс». Вы увидите форму с входными параметрами, её необходимо заполнить: укажите название версии и при необходимости примечания к выпуску:
2.4. Заполнив форму, нажмите Run workflow. Action запустится. Здесь же можно посмотреть информацию о рабочем процессе и возникших во время его выполнения ошибках:
2.5. По завершении действия вы можете проверить свой API на наличие определения и новой версии:
Автоматизация
Этот GitHub Action позволяет вручную установить номер версии и примечания к выпуску в форме Run workflow. Однако выполнение рабочего процесса можно автоматизировать, рассчитав входные значения без вмешательства человека.
Например:
Получить версию из поля определения info.version и сравнить его с последней опубликованной версией вашей API в рабочей области Postman.
Определить примечания к выпуску на основе последних коммитов в репозитории. GitHub предоставляет API для получения последней версии репозитория.
Включите эти два пункта в рабочий процесс, и данные о номере версии с примечаниями к выпуску будут автоматически переданы в GitHub Action. Это действенный способ использования возможностей Postman API для автоматизации процесса разработки ПО.
Заключение
Мы рассмотрели один из способов использования возможностей Postman API для автоматизации процесса разработки программного обеспечения. Изучив документацию по API Postman, можно найти и другие.
Работу описанной выше связки мы успешно протестировали в одном из приложений, где использовали API МТС Exolve для бизнес-коммуникаций. Программу проверили при помощи Postman, а затем успешно развернули на GitHub, получив на выходе стабильный API