Любое изменение интеграционного контракта затрагивает потребителей — партнёров, мобильные клиенты, смежные команды. Версионирование API (API versioning) и политика жизненного цикла (API lifecycle) отвечают на вопрос: как эволюционировать интерфейс, не ломая действующие интеграции и не накапливая бесконечный техдолг. Для системного аналитика это мост между интерфейсами систем и требованиями к обратной совместимости, миграции, срокам поддержки и коммуникации изменений.

1. Суть темы

Версия API — идентифицируемый снимок контракта и поведения: ресурсы, операции, схемы payload, коды ошибок, правила валидации, pagination, webhooks. Жизненный цикл API — последовательность статусов от проектирования до вывода из эксплуатации (sunset), с правилами переходов между ними. Жизненный цикл API — частный случай эволюции продукта в рамках SDLC: здесь фокус на обязательствах перед потребителями контракта, а не на статусах отдельного требования.

Версионирование задаёт как изменения маркируются и как клиент выбирает версию. Политика жизненного цикла — как долго версия поддерживается и какие обязательства организация даёт потребителям.

На практике аналитик разводит три независимые оси — их нельзя подменять одной «рекомендацией провайдера»:

ОсьВопросПримеры решений
Способ указания версии (version discovery)Как клиент сообщает серверу, какой снимок контракта нуженPath /v2/, header API-Version, query ?api-version=, media type в Accept
Политика выпуска breaking (release policy)Когда и как оформляется несовместимое изменениеНовый major в path; новая dated version; additive-only без major
Источник истины версии (source of truth)Где зафиксирована «активная» версия для данного потребителяURL запроса; API key → pinned version в catalog; billing-account date (Stripe-style)

Google Cloud API Design Guide относится к первой и второй осям: major в path, минимум параллельных major. Stripe — к третьей: каждый аккаунт прикреплён к dated version; breaking оформляется новой датой, а не сменой path у клиента. Это не конкурирующие рекомендации, а разные модели governance: path — идентификатор major, calendar — привязка аккаунта к снимку. В спецификации фиксируйте все три оси явно.

Типовая модель жизненного цикла:

stateDiagram-v2
    [*] --> Draft
    Draft --> Beta: preview release
    Beta --> GA: стабилизация контракта
    GA --> Deprecated: объявление sunset
    Deprecated --> Retired: end-of-life
    Retired --> [*]
    Beta --> Draft: breaking в preview

Переход Beta → Draft (breaking в preview) означает откат нестабильного контракта: потребители preview должны были интегрироваться без SLA на production; после отката им нужен новый migration path или повторная регистрация в preview-программе. В политике preview зафиксируйте: кто уведомляется, какой срок на адаптацию и запрет ли production-нагрузки без waiver.

Граница этой статьи:

В зоне этой статьиВынесено в соседние заметки
Стратегии версионирования, breaking/non-breaking, deprecation, sunsetФорматы контрактов OpenAPI, AsyncAPI, Protobuf — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)
Выбор протокола и особенности эволюции REST, gRPC, GraphQL03.05.02 Синхронные протоколы (REST, gRPC, GraphQL), 03.05.04 Контрактное программирование и протоколы (gRPC, GraphQL)
REST + OpenAPI углублённо03.05.02 REST и OpenAPI спецификации
Версионирование событий и схем в Kafka03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events), 03.05.06 Event-Driven Architecture
Архитектура интеграции03.05.01 Виды интеграции (точка-точка, ESB, API-led)
Управление изменениями на уровне требований02.05.05 Жизненный цикл требования, 02.05.02 Управление изменениями (Change Control Board)
SOAP / WSDL10.01.05 Шаблон спецификации SOAP API — отдельная политика namespace и binding

Ключевое различение для работы на проекте:

ПонятиеЧто фиксирует аналитик
Breaking change (несовместимое изменение)Изменение, при котором существующий клиент без доработки может получить ошибки или некорректные данные — в запросе, ответе или семантике
Backward compatibility (обратная совместимость)Серверная: новая версия принимает старые запросы и сохраняет ожидаемую семантику для non-breaking сценариев. Клиентская: старый клиент корректно работает с новым сервером — в том числе при изменениях ответа (новые поля, коды ошибок, формат pagination). Добавление optional поля в response обычно non-breaking; смена обязательности или семантики поля в response — частый спорный breaking
Deprecation (устаревание)Официальное объявление: элемент или версия не рекомендуется к использованию и будет удалена по графику
Sunset / End-of-Life (EOL)Дата или событие, после которого версия или эндпоинт больше не поддерживается

Без формального определения breaking change и сроков deprecation споры между командами превращаются в «тихие» поломки интеграций в production.

2. Ключевые понятия

Стратегии указания версии

Организация выбирает один primary способ привязки клиента к версии; дополнительные — только как fallback для внутренних потребителей. Источник истины — один канонический: catalog, gateway policy или pinned version на API key; URL, header и billing-date должны согласовываться с ним, а не противоречить.

СтратегияПримерПлюсыОграничения
URI path/v1/orders, /v2/ordersПросто для потребителя, явно в URLДублирование маршрутов, раздувание surface area
Query parameter?api-version=2024-01-01Гибко, не меняет pathЛегко «забыть» в клиенте; кэш может игнорировать
HeaderAPI-Version: 2, Accept: application/vnd.company.v2+jsonЧистый URL, подходит для внутренних APIСложнее тестировать «в браузере»; CDN может не учитывать заголовки
Media type (content negotiation)Версия в Accept / Content-TypeСоответствует REST-подходуТребует дисциплины у всех потребителей
Hostname / subdomainv2.api.example.comИзоляция на уровне инфраструктурыРеже; сложнее governance
Date-based / calendar versioningПривязка аккаунта к дате релиза (Stripe-style)Предсказуемые «снимки» контрактаКлиент «заморожен» на дате до явной миграции; в multi-tenant нужно решить: одна dated version на tenant или глобальный rollout

Пример согласованной тройки осей: внешний REST API — primary path /v2/ (discovery), breaking → новый path /v3/ (release policy), catalog и API key хранят pinned major (source of truth); SemVer в changelog (2.4.0) описывает non-breaking/minor внутри major, а не заменяет path.

Эволюция контракта по стеку

Правила governance (breaking, deprecation, sunset) едины; механика эволюции контракта зависит от протокола. REST/OpenAPI, GraphQL, gRPC/Protobuf и AsyncAPI/Kafka решают совместимость по-разному — детали field numbers, @deprecated, schema registry и режимы Avro — в 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL), 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf) и 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events). Здесь достаточно правил для сквозного governance:

  • версия HTTP API ≠ версия сообщения в topic — для сквозных сценариев фиксируйте обе оси в compatibility matrix;
  • GraphQL: deprecation поля в schema (@deprecated) — не новый path major; breaking наступает при удалении поля после срока deprecation, а не при смене URL; в matrix отдельно фиксируйте min client schema version;
  • gRPC/Protobuf: field numbers и backward-compatible wire format — см. соседние заметки, здесь только связь с matrix и release policy.

Семантика версий (SemVer) в контексте API

Semantic Versioning (SemVer) — ориентир для документации и changelog, не обязательная привязка клиента:

КомпонентСмысл для API
MAJORBreaking changes — новая базовая линия контракта
MINORОбратно совместимые расширения: новые поля, эндпоинты, необязательные параметры
PATCHИсправления без изменения контракта для клиента: багфиксы, производительность

На практике публичные API часто комбинируют SemVer в release notes с date-based или header-based привязкой клиента. Breaking change в minor/patch подрывает доверие к политике — это организационная ошибка, а не техническая.

Статусы жизненного цикла

СтатусСмыслОбязательства перед потребителями
Draft / DesignПроектирование, ревью SA и архитектораНет SLA; контракт может меняться
Beta / PreviewОграниченная аудиторияBreaking changes допустимы; откат Beta → Draft по политике preview; production без явного согласия запрещён
GA (Generally Available)Стабильная поддержкаSLA, предсказуемая политика изменений, формальный deprecation перед удалением
DeprecatedРаботает, но объявлен срок sunsetПредупреждения в документации, заголовок Deprecation (RFC 9745), дата EOL в Sunset (RFC 8594), migration guide
Retired / SunsetВыведено из эксплуатацииНедоступно или read-only по исключению

Статусы целесообразно фиксировать в API catalog / реестре API вместе с владельцем, политикой изменений и реестром потребителей. Deprecated endpoint и retired topic в async-ландscape — разные артефакты с общей логикой статусов; синтаксис — в 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf).

Contract-first и граница SA vs платформы

Contract-first: изменение контракта начинается с PR к OpenAPI/AsyncAPI (или аналогу); код и тесты следуют spec. Code-first: spec генерируется из кода — риск drift.

Не всё из toolchain — зона SA. Разводите явно:

Что описывает SA в SRS / NFR / ADRЧто SA принимает как constraint от платформы
Политика breaking, сроки deprecation, default version, dual-runНаличие oasdiff / openapi-diff в CI, правила блокировки pipeline
Compatibility matrix, реестр потребителей, артефакты коммуникацииКонкретный API gateway, routing policy, schema registry
Требования к audit trail версии контрактаРеализация логирования, retention, хранилище spec snapshot
Acceptance criteria GA и sunsetНастройка мониторинга adoption, алертов по Deprecation headers

SA фиксирует что должно быть обеспечено и как проверить; команда платформы/DevOps — как реализовано (07.06 CICD и конвейеры — влияние на требования, статическая проверка контракта). Без этой границы governance остаётся на бумаге или уходит целиком в инженерный backlog без трассировки к требованиям.

Поведение по умолчанию без указания версии

Обязательное поле спецификации — не только «запрет floating default», но и явная политика:

Политика defaultКогда уместнаРиск
Latest GAВнутренние API с коротким циклом миграцииКлиент без version «плывёт» на новый GA — нужен мониторинг
Oldest supportedB2B с длинным deprecationНовые клиенты стартуют на legacy до миграции
Pinned per API key / tenantCalendar versioning, multi-tenantCatalog — source of truth; gateway читает pin

Запрет «молчаливого» перевода default на версию с breaking — отдельное требование к релизному процессу. Смена того, какая версия считается latest GA, — само по себе изменение governance: floating-клиенты получают новый контракт без явного выбора. Относите смену default major к breaking или выделяйте отдельный gate с коммуникацией и фиксированным окном миграции — иначе minor-релиз превращается в скрытый major для части потребителей.

Артефакты версионирования

АртефактНазначение для аналитика
Changelog / release notesЧто изменилось; breaking vs non-breaking; миграционные шаги; каналы: developer portal, email, status page — с владельцем коммуникации
Migration guideПошаговый переход v1→v2 или между dated versions
Compatibility matrixКакие системы-потребители на какой версии; webhook URL, min app version для mobile; связь с [[02.03.04 Трассировка требований (концепция)
OpenAPI / AsyncAPI diffАвтоматическое сравнение спецификаций между версиями в CI
API governance policyКто утверждает breaking change; минимальный срок deprecation
HTTP Deprecation / Sunset headersМашиночитаемые сигналы: Deprecation (RFC 9745) + Sunset (RFC 8594)

В словаре данных полезно отражать версионность полей: introducedIn, deprecatedSince, removedIn.

Критерии breaking vs non-breaking

Чеклист для ревью изменения контракта:

Обычно breaking:

  • Удаление или переименование ресурса, поля, значения enum без alias
  • Смена типа, формата или обязательности поля (в request или response)
  • Изменение кодов HTTP/ошибок, влияющее на ветвление клиента
  • Смена формата pagination (cursor, offset) или обязательных параметров страницы
  • Ужесточение валидации: ранее принимавшиеся запросы → 4xx
  • Изменение бизнес-семантики при том же контракте
  • Смена контракта webhook/callback без версионирования URL или payload schema

Обычно non-breaking:

  • Добавление optional полей и параметров
  • Новые эндпоинты и операции
  • Новые значения enum (если клиент — tolerant reader; для mobile с жёстким switch по enum и лагом app store — часто breaking)
  • Расширение диапазона допустимых значений без ужесточения

При смене версии сохраняйте идемпотентность ключевых операций и correlation id в контракте ошибок — иначе миграция ломает трассировку и retry-логику потребителей.

Спорные случаи фиксируйте в политике изменений проекта — единый критерий важнее «интуиции команды».

3. Как применяется в работе аналитика

Что описывать в требованиях и спецификации

  1. Политика изменений — формальное определение breaking; когда нужен новый major или новая dated version.
  2. Три оси governance — discovery, release policy, source of truth (раздел 1).
  3. Contract-first и граница SA/платформы — что SA пишет в SRS/NFR/ADR, что принимает как platform constraint (таблица выше).
  4. Стратегия версионирования — primary способ + fallback; политика default без version; правила смены latest GA.
  5. Минимальные сроки — deprecation не менее N месяцев для внешних; правила preview.
  6. Обязательные артефакты релиза — OpenAPI/AsyncAPI, changelog, migration guide, catalog; для SOAP — 10.01.05 Шаблон спецификации SOAP API.
  7. Кросс-системные зависимости — реестр потребителей, webhook, mobile min version, impact analysis — 02.05.01 Управление зависимостями между требованиями; matrix связать с трассировкой изменений контракта к требованиям и релизам.
  8. Dual-run (если v1 и v2 работают параллельно) — режим: параллельная маршрутизация на gateway или только документация без двойной обработки; срок dual-run; критерий выключения v1-side; поведение webhook/callback при двух версиях (отдельный URL, версия в payload, fan-out).
  9. Rate limits и quotas — при смене версии лимиты могут быть привязаны к product tier; согласовать с 03.06.03 Rate Limiting — управление пропускной способностью.
  10. Наблюдаемость — метрики adoption: доля трафика по версии, unique consumers, рост 4xx после объявления sunset, время до нулевого трафика на deprecated.
  11. Audit trail версии контракта — для регулируемых доменов (финтех, healthcare): логирование api-version / dated version и spec snapshot на момент транзакции; срок хранения; связь с incident investigation.
  12. Коммуникация sunset — минимальный набор артефактов: changelog + migration guide; письмо/уведомление партнёру с владельцем sign-off; status page; для B2B — нужен ли amendment к договору при EOL (ожидания заказчика, регуляторика).

Пункты входят в шаблон спецификации REST API, NFR и ADR. Перед ревью контракта — ручная проверка deprecation headers и diff spec (практика работы с API).

Типовой workflow при изменении API

flowchart LR
    A[Запрос изменения] --> B{Breaking?}
    B -->|Нет| C[Minor/patch в текущей версии]
    B -->|Да| D[Новая версия / dated release]
    D --> E[Спека + migration guide]
    E --> F[Deprecation старого]
    F --> G[Коммуникация потребителям]
    G --> H[Мониторинг adoption]
    H --> I[Sunset по политике]
    C --> J[Changelog + CI diff]
    J --> K[Impact + коммуникация<br/>для жёстких клиентов]

Ветка non-breaking не заканчивается на CI diff: новые enum, поля в response и ужесточение документации могут ломать mobile и B2B с жёстким парсингом — нужен impact по matrix и точечная коммуникация.

Acceptance criteria для GA новой версии (v2) — критерии приёмки релиза контракта:

  • Спецификация, changelog и migration guide опубликованы до GA v2.
  • Документированные сценарии v2 проходят контрактные и интеграционные проверки на v2.
  • Если dual-run: в спецификации описаны режим (маршрутизация vs документация), срок, критерий выключения v1-side, правила webhook при двух версиях; deprecated-элементы v1 помечены в spec и заголовках.
  • SDK/генерируемые клиенты (если есть) выпущены или зафиксирован срок.

Acceptance criteria для sunset v1 — отдельный gate, не смешивать с GA v2:

  • Трафик на v1 ниже порога политики (например, <1% requests / 0 unique B2B partners).
  • Потребители из реестра подтвердили миграцию или формально приняли риск отключения.
  • Dual-run завершён по задокументированному критерию; webhook v1 отключены или перенаправлены.
  • Нет открытых инцидентов миграции; rate limits и billing tier согласованы для v2.

Роль SA в integration-landscape

Практические ориентиры по срокам

АудиторияТипичный минимум deprecationКомментарий
Внешние партнёры (B2B)6–12 месяцев и болееЗависит от контракта и SLA
Внутренние команды1–3 месяцаПри реестре потребителей и мониторинге
Preview / Beta0 (breaking допустим)Production-нагрузка без waiver запрещена

Перед sunset: активный трафик, инциденты миграции, контрактные обязательства — регуляторика и compliance, ожидания заказчика по срокам EOL.

4. Типовые ошибки и ограничения

Ограничения стратегий версионирования — в таблице раздела 2; здесь фиксируем типичные ошибки процесса и организационные риски.

Типичные ошибки

  1. Нет формального определения breaking change — «тихие» поломки и споры на релизе.
  2. Смешение GA v2 и sunset v1 в одних acceptance criteria — преждевременное отключение или вечный dual-run.
  3. Dual-run объявлен, но не описан — нет режима, срока, критерия выключения v1, правил webhook.
  4. Не описана политика default — аналитик не может заполнить шаблон REST API; смена latest GA без gate ломает floating-клиентов.
  5. Breaking change в minor/patch — потеря доверия к semver.
  6. Non-breaking без impact-анализа — «мы только поле добавили в ответ» vs жёсткий mobile/B2B-клиент; workflow обрывается на CI diff.
  7. Несколько несогласованных способов версии — разные default и source of truth.
  8. Не ведётся учёт потребителей — sunset «в слепую»; см. 08.05 Управление рисками на этапе анализа.
  9. Preview без правил отката Beta → Draft — интеграторы preview без плана.
  10. Игнорирование async/schema registry — см. 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events), 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ), 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ).
  11. Webhook и mobile вне scope versioning — callback URL и min app version не в matrix.
  12. SA не участвует в changelog и sunset-коммуникации — теряется бизнес-семантика; нет sign-off на письма партнёрам.
  13. Нет audit trail версии контракта — при расследовании нельзя восстановить, какой spec действовал на момент транзакции.

Риски для организации

  • SLA и штрафы при внезапном EOL — 08.05 Управление рисками на этапе анализа.
  • Каскадные сбои при shared API gateway и неявной маршрутизации версий.
  • Аудит и compliance: невозможность доказать версию контракта на момент транзакции — финтех, healthcare; зеркальное требование к логированию — в п. 11 раздела 3.

При выборе стратегии оценивайте стоимость поддержки N версий и скорость миграции аудитории.

Связи с другими разделами базы

Источники и дополнительные материалы

Книги и стандарты

Спецификации и инструменты

Статьи и практики провайдеров