Версионирование и документирование API магазина

API магазина редко существует само по себе: на нём висят мобильное приложение, интеграции с 1С и маркетплейсами, партнёрские сервисы и внутренние потребители. И как только у API появляются внешние клиенты, любое неаккуратное изменение перестаёт быть «просто правкой» — оно превращается в аварию у тех, кто на этот API завязан. Убрали поле, поменяли формат — и чужая интеграция легла.

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

Зачем магазину версионировать API

Суть проблемы в том, что у вас и у потребителей API разные скорости. Вы хотите развивать магазин: добавлять поля, менять структуру ответов, улучшать методы. Потребители хотят стабильности: чтобы их код, написанный полгода назад, продолжал работать. Без версионирования эти интересы сталкиваются, и каждое улучшение рискует сломать чью-то интеграцию.

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

Что ломает потребителей API

Чтобы управлять совместимостью, нужно чётко понимать, какие изменения ломающие, а какие безопасные.

Общее правило легко запомнить: добавлять можно, убирать и менять — нельзя без новой версии. Пока вы только расширяете контракт, старые клиенты продолжают работать. Как только вы что-то убираете или меняете — это новая версия.

Стратегии версионирования

Есть несколько способов обозначить версию, и у каждого свои плюсы:

• Версия в URL. /api/v1/, /api/v2/ — наглядно, легко тестировать в браузере, однозначно в логах. Самый практичный вариант для магазина с внешними интеграторами.
• Версия в заголовке. Через Accept или собственный заголовок — чище с точки зрения REST, но менее прозрачно в отладке и кэшировании.
• Версия в параметре. ?version=2 — просто, но легко потерять и неудобно для кэша.

Для API магазина, которым пользуются внешние разработчики, обычно выбирают версионирование в URL: оно самое понятное для потребителей и прозрачное в диагностике. Главное — выбрать один способ и придерживаться его во всём API, а не смешивать.

Обратная совместимость

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

Новую версию заводят только тогда, когда без ломающего изменения действительно не обойтись. Чем реже вы плодите версии, тем меньше их нужно поддерживать параллельно. Хорошее API годами живёт на одной мажорной версии, аккуратно прирастая необязательными полями.

Семантика версий и правила изменений

Полезно применять к API семантическое версионирование в упрощённом виде. Для внешних потребителей значима мажорная версия — она меняется только при ломающих изменениях. Минорные улучшения и исправления живут внутри мажорной версии и не требуют миграции клиентов.

1. Мажор — только на ломающее. v1 → v2 выпускается, когда без несовместимого изменения нельзя.
2. Минор — на добавление. Новые необязательные поля и методы внутри той же мажорной версии.
3. Патч — на исправления. Багфиксы без изменения контракта, прозрачные для клиентов.
4. Явный журнал изменений. Каждое изменение фиксируется в changelog с пометкой совместимости.

Прозрачный журнал изменений — часть контракта. Потребители должны видеть, что изменилось и безопасно ли это, не читая исходники.

Документация как источник правды

Главная беда документации API — она устаревает. Разработчик поменял метод, а описание осталось прежним, и потребитель работает по неверной инструкции. Лечится это переносом источника правды в машиночитаемый формат, который живёт рядом с кодом.

Спецификация становится не «документом для людей», а формальным контрактом: из неё генерируются и человекочитаемая документация, и клиентские библиотеки, и тесты. Обновляется она в том же коммите, что и изменение кода. Тогда документация физически не может разойтись с реальностью, потому что она часть кодовой базы. Про организацию сервисного слоя, который стоит за таким API, мы писали в материале про D7 ORM в 1С-Битрикс.

OpenAPI и генерация артефактов

Стандарт де-факто для описания REST API — OpenAPI. Это машиночитаемая спецификация, из которой автоматически растут полезные артефакты:

• Человекочитаемая документация. Интерактивная страница с методами, параметрами и примерами — генерируется из спецификации.
• Клиентские библиотеки. SDK под разные языки, чтобы интеграторы не писали клиента с нуля.
• Заглушки и моки. Потребители тестируют интеграцию, не дожидаясь готового сервера.
• Контрактные тесты. Проверка, что реальные ответы совпадают со спецификацией.

Ключевая дисциплина — спецификация первична. Сначала описывается контракт, потом реализуется код, а не наоборот. Тогда OpenAPI остаётся единым источником правды, а не запоздалой документацией задним числом.

Депрекация и вывод из эксплуатации

Рано или поздно старую версию нужно отключить. Делать это резко — значит устроить аварию всем, кто не успел мигрировать. Правильный путь — управляемая депрекация.

1. Объявите устаревание. Пометьте версию как deprecated в документации и changelog.
2. Добавьте заголовки. В ответы старой версии — Deprecation и Sunset с датой отключения.
3. Соберите статистику. Отследите, кто и как активно пользуется старой версией.
4. Уведомите потребителей. Свяжитесь с активными клиентами, помогите с миграцией.
5. Дайте переходный период. Разумный срок на переход, а не пара дней.
6. Отключайте по факту. Гасите версию, когда трафик упал до нуля или согласован с оставшимися.

Такой процесс превращает отключение версии из аварии в плановое событие, к которому все готовы заранее.

Реализация в 1С-Битрикс

В 1С-Битрикс REST-API строится на модуле rest, событиях и обработчиках. Версионирование накладывается сверху понятной архитектурой:

• Разделение маршрутов. Разные версии — разные префиксы (/api/v1/, /api/v2/) с собственными контроллерами.
• Общий сервисный слой. Бизнес-логика выносится в сервисы на D7, чтобы версии переиспользовали код, а не дублировали его.
• События для расширения. Поведение аккуратно расширяется через события, не меняя контракт существующей версии.
• Ограничение методов и прав. Каждая версия отдаёт только разрешённые методы, доступ контролируется ключами и правами.

Отдельная важная тема — безопасность доступа к API: ключи, ограничение методов, защита вебхуков. Её мы подробно разбирали в статье про REST, вебхуки и безопасность в 1С-Битрикс. Версионируемое API без продуманной безопасности — половина решения.

Контрактные тесты и деплой

Версионирование защищает от запланированных изменений, а контрактные тесты — от случайных. Тест сверяет реальные ответы API со спецификацией OpenAPI: поля, типы, коды. Если разработчик нечаянно убрал поле или поменял тип, тест падает ещё до релиза, а не после жалоб интеграторов.

Эти проверки встраиваются в конвейер сборки и деплоя: код проходит ревью и контрактные тесты, выкатывается на стенд, затем в прод через управляемый деплой с откатом. Так несовместимое изменение физически не уедет в продакшен незамеченным. Про организацию такого конвейера мы писали в материале про CI/CD и деплой в 1С-Битрикс, а про надёжную среду выполнения — в статье о хостинге и BitrixVM.

Частые ошибки

• Изменения без версии. Убрали поле «по-тихому» — легли чужие интеграции.
• Документация задним числом. Описание пишут после кода, оно устаревает и врёт.
• Резкое отключение версии. Погасили старую версию без депрекации — авария у всех потребителей.
• Смешение способов версионирования. Часть методов в URL, часть в заголовке — путаница у интеграторов.
• Плодят версии по мелочам. Новая мажорная версия ради необязательного поля — рост стоимости поддержки.
• Нет контрактных тестов. Ломающее изменение уезжает в прод незамеченным.
• Дублирование логики между версиями. Нет общего сервисного слоя — правки надо вносить в каждую версию.

Чек-лист внедрения

1. Выбрана стратегия версий. Один способ (обычно URL) применён ко всему API.
2. Правила совместимости заданы. Команда знает, что ломающее, а что нет, и как это выпускать.
3. Есть спецификация OpenAPI. Контракт описан машиночитаемо и лежит рядом с кодом.
4. Артефакты генерируются. Документация и клиенты растут из спецификации, не пишутся вручную.
5. Общий сервисный слой. Логика в сервисах на D7, версии переиспользуют код.
6. Процесс депрекации описан. Заголовки Deprecation/Sunset, статистика, уведомления, переходный период.
7. Контрактные тесты в CI. Ответы сверяются со спецификацией на каждом деплое.
8. Безопасность настроена. Ключи, права, ограничение методов по версиям.

Вывод

API магазина — это продукт с внешними потребителями, и относиться к нему нужно как к продукту. Версионирование даёт развивать его, не ломая интеграции: старые версии живут, новые добавляются, а клиенты мигрируют в своём темпе. Простое правило «добавлять можно, убирать и менять — только через новую версию» снимает большую часть проблем совместимости.

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