OpenCollection: работем с разными API, тестируем, документируем и комитим в GIT

Сегодня хочу рассказать об OpenCollection — открытой спецификации для описания и обмена коллекциями API.

Если вы работаете с API, особенно в e-commerce на платформах вроде WordPress и WooCommerce, это может оказаться полезным. Разберёмся, что это такое, где применяется, чем отличается от OpenAPI и как использовать в проектах.

Что такое OpenCollection?

OpenCollection — открытая спецификация для создания и распространения коллекций API, разработанная командой Bruno (инструмент usebruno.com). Это формат, ориентированный на разработчиков, с упором на простоту и совместную работу. На момент написания актуальная версия — 0.1. Спецификация основана на YAML, поэтому её удобно читать и редактировать.

В отличие от решений вроде Postman, которые часто используют проприетарные форматы, OpenCollection — открытый стандарт. Коллекции хранятся в YAML-файлах, их легко хранить в репозитории, отслеживать изменения в Git и снижать зависимость от конкретного вендора.

Ключевые особенности:

• Простой YAML-формат: удобно редактировать в любом редакторе и сравнивать изменения в Git.
• Хранение документации по API в GIT: очень удобно иметь всю связанную документацию по работе с API сайта и внешними сервисами в 1 месте. Без облаков. С сохранением истории.
• Независимость от инструментов: можно импортировать в Bruno, запускать через CLI, автоматизировать в CI/CD, генерировать документацию или редактировать в VS Code.
• Переменные и окружения: переменные задаются один раз и используются в разных окружениях (local, staging, production). Это упрощает переключение и помогает держать секреты под контролем.
• Встроенные тесты: поддерживаются проверки ответов, статус-кодов, времени отклика и наличия нужного контента. Это хорошо ложится на CI/CD.

Сценарии использования OpenCollection

OpenCollection подходит, когда нужно делиться запросами и автоматизировать работу с API.

Типичные сценарии:

• Описание и обмен HTTP-запросами: коллекции для GET /orders, POST /users и т. п., включая методы, URL, заголовки и тела запросов. Удобно для команды, где разработчики делятся примерами.
• Workflow для разных окружений: используйте переменные вроде baseUrl, чтобы быстро переключаться между dev и prod.
• Автоматизация тестирования: запускайте коллекции в пайплайнах CI/CD и проверяйте, что API не сломалось после изменений.
• Генерация документации: превращайте коллекции в «живую» исполняемую документацию, которую можно запускать.
• Работа из IDE: редактируйте коллекции прямо в VS Code без отдельного приложения.

Если кратко, OpenCollection — про портативные, «дружелюбные к Git» коллекции запросов и сценариев.

Сравнение OpenCollection (Bruno) и OpenAPI (Swagger)

OpenCollection и OpenAPI не столько конкурируют, сколько дополняют друг друга. OpenAPI отвечает на вопрос «что такое API», а OpenCollection — «как им пользоваться».

• OpenAPI:
  • описывает контракт API: эндпоинты, методы, схемы запросов и ответов, аутентификацию, типы данных, правила валидации;
  • используется для генерации документации и SDK, а также для валидации payload;
  • это «чертёж»: структура и требования.
• OpenCollection:
  • описывает практические сценарии: последовательности запросов, подготовительные скрипты, тесты, переменные окружения и секреты;
  • подходит для runnable-примеров, исполняемой документации и тестирования workflow;
  • это «инструкция»: шаги и примеры.

Практическая рекомендация:

• выбирайте OpenAPI, когда нужен контракт и генерация артефактов (документация, SDK, валидация);
• выбирайте OpenCollection, когда важны воспроизводимые сценарии, примеры и автоматизация.

Как применять OpenCollection в WordPress и WooCommerce

WordPress и WooCommerce дают REST API для работы с магазином (заказы, товары, пользователи). Формат позволяет использовать спецификацию как удобный способ хранить и выполнять запросы к API связанным с сайтом.

У любого современного сайта, особенно на WordPress и WooCommerce, обычно есть не один, а целый набор API:

• Типовые API платформы: WordPress REST API (/wp-json/wp/v2/), WooCommerce REST API (/wp-json/wc/v3/).
• Платёжные шлюзы: Сбер, ЮКасса и другие — каждый со своими эндпоинтами и авторизацией.
• Интеграции с чат-ботами: Telegram Bot API, WhatsApp Business API и прочие мессенджеры.
• Внешние сервисы: CRM (Битрикс24, amoCRM), склады, маркетплейсы, email-рассылки, аналитика — список может быть длинным.

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

Решение: одна папка в Git-репозитории проекта с OpenCollection-коллекциями, где собраны все важные API.

Преимущества такого подхода:

• Всё в одном месте: разработчик открывает папку api-collections/ и сразу видит список групп — WooCommerce, Платежи, Telegram Bot, CRM и т. д. Каждая группа содержит типовые роуты с готовыми примерами.
• Переменные из .env: базовые URL, ключи API, токены и секреты подтягиваются из переменных окружения. Не нужно вручную править каждый запрос при переходе с dev на production.
• Экономия времени: вместо того чтобы искать документацию или копировать curl-команды из истории терминала, разработчик запускает готовый запрос одной командой или кликом в Bruno.
• История изменений: коллекции хранятся в Git, поэтому видны все изменения: кто, когда и зачем обновил эндпоинт или добавил новый тест. Это упрощает код-ревью и помогает отследить причины проблем.
• Актуализация документации: когда API меняется (новая версия, новый эндпоинт, изменённая авторизация), правки вносятся прямо в коллекцию и коммитятся. Документация остаётся живой и синхронизированной с кодом.
• Онбординг новых разработчиков: новичок клонирует репозиторий, настраивает .env и сразу получает рабочие примеры всех интеграций. Не нужно часами разбираться, как «правильно стучаться» в тот или иной сервис.

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

Вывод

OpenCollection — современный и открытый подход к работе с API-коллекциями: простой, «Git-friendly» и ориентированный на практику. Он хорошо дополняет OpenAPI: один задаёт контракт, другой — сценарии использования и проверок. Для WordPress и WooCommerce это удобный способ хранить запросы и тесты, особенно если вы активно интегрируетесь с внешними сервисами.