Стабильность API, версионирование, депрекация и вывод из эксплуатации

Эта страница — контракт стабильности для всего, что программируется против control plane. Она описывает, что является стабильным, как сигнализируется ломающее изменение, и как долго депрекированная поверхность продолжает работать. Соблюдение обеспечивается в кодовой базе, а не в прозе: таблица депрекации, заголовки ответов, маркеры OpenAPI и проверки окон ниже — все они управляются из единого in-code-объявления (core/api/stability.go), и вывод из эксплуатации, назначенный раньше, чем позволяет политика, проваливает сборку.

Покрытые поверхности и уровни

Поверхность	Версионируется по	Уровень сегодня
Базовый REST-контракт — пути в выдаваемом документе OpenAPI	мажорной версии в URL (`/v1/…`)	stable
gRPC-зеркало — `ControlPlane` в proto-пакете `olivares.api.v1`	мажорной версии proto-пакета	stable (замороженное зеркало)
Live-ingest / протокол коннектора — proto-пакет `olivares.sdk.v1`	мажорной версии proto-пакета + плагин `ProtocolVersion`	stable (заморожено)
SDK коннекторов (Go) — модули `sdk`, `sdk/plugin` (авторская поверхность)	semver модуля — теги `sdk/v`, `sdk/plugin/v` начиная с первого публичного релиза	stable v1 (Go-контракт; строка протокола выше)
Контракт шины событий (AsyncAPI 3.0) — её типы событий — это также то, что платформа событий доставляет внешним webhook-подпискам; маршруты управления подписками — это маршруты модулей (`/v1/m/eventing/`, вне контракта), но каждый тип события несёт собственный уровень стабильности из in-code-каталога	`info.version` (`1.0.0-preview`)	beta (документ); уровни по типам для типов событий
Terraform-провайдер	собственный semver (теги `terraform-provider-v*`)	stable, MAJOR отслеживает API v1
Клиентские SDK (Go / Java / Python / TypeScript)	собственный semver; MAJOR отслеживает мажорную версию API с момента GA	beta (pre-1.0-пакеты)
Всё, что не перечислено — маршруты модулей `/v1/m/<ns>/`, SCIM, федерация, внутренние компоненты	—	out of contract

Уровни. Stable-поверхность не меняется несовместимым образом в пределах своей мажорной версии; её удаление или изменение требует процесса депрекации ниже. Beta-поверхность ещё может менять свою форму, но получает ту же сигнализацию и более короткое окно. Out-of-contract-поверхность (в частности, маршруты модулей, которые намеренно находятся вне документа OpenAPI — см. обзор справочника) не несёт никакого обещания совместимости; её контракты живут в типизированных интерфейсах, поставляемых с продуктом.

Каждая операция в документе OpenAPI несёт машиночитаемый маркер x-stability, а сам документ ссылается на эту страницу в info.x-stability-policy.

Что считается ломающим изменением

Для stable-поверхности всё нижеперечисленное является ломающим и подпадает под процесс ниже:

удаление или переименование пути, метода, поля запроса, поля ответа или кода ошибки code;
изменение типа или смысла поля, либо превращение опционального поля запроса в обязательное;
ужесточение аутентификации/авторизации так, что ранее валидный вызов начинает проваливаться;
для gRPC/protobuf: всё, что отклоняет buf breaking (набор правил FILE).

Не являются ломающими: добавление эндпойнтов, добавление опциональных параметров запроса, добавление полей ответа, добавление новых кодов ошибок для новых режимов отказа и добавление заголовков ответа. Клиенты должны толерантно относиться к неизвестным JSON-полям.

Версионирование

REST версионируется в URL: весь стабильный контракт живёт под /v1/. Несовместимое изменение выходит под /v2/, а /v1/ входит в депрекацию — никогда не ломается на месте.
gRPC версионируется по proto-пакету: olivares.api.v1 / olivares.sdk.v1. Несовместимое изменение требует новой мажорной версии пакета (…v2); оба контракта охраняются buf breaking против main (task proto:breaking).
Terraform-провайдер выпускается независимо (теги terraform-provider-v*); его MAJOR отслеживает мажорную версию API, на которой он говорит.
Клиентские SDK встраивают API_VERSION (мажорную версию контракта, из которой они были сгенерированы) и SPEC_HASH (точный снимок OpenAPI) — APIVersion и SpecHash в Go; с момента GA их MAJOR отслеживает мажорную версию API.
SDK коннекторов (Go-контракт, против которого собираются сторонние коннекторы) версионируется per-module-тегами semver (sdk/vX.Y.Z, sdk/plugin/vX.Y.Z) и охраняется той же стеной buf breaking на своём протокольном контракте. Интерфейсы, которые реализует автор, никогда не получают новых методов в пределах мажорной версии; новая возможность приходит как новые опциональные интерфейсы. Полная политика поставляется с модулем (sdk/VERSIONING.md); жизненный цикл авторства описан в Сборка и поставка коннектора.

Процесс депрекации и сигнализация

Депрекация — это одна объявленная запись в in-code-таблице плюс руководство по миграции; всё остальное следует из неё механически.

Анонсируйте. Запись появляется с датой анонса и URL руководства по миграции. С этого момента каждый ответ депрекированного маршрута несёт заголовок RFC 9745 и ссылку на руководство, а операция OpenAPI получает deprecated: true, x-deprecated-at и x-migration-guide:
```
Deprecation: @1780272000
Link: <https://olivares.ai/docs/how-to/migrate-example/>; rel="deprecation"
```
Назначьте вывод из эксплуатации. Когда дата вывода зафиксирована, ответы добавляют заголовок RFC 8594 (а спецификация получает x-sunset-at):
```
Sunset: Thu, 01 Jun 2028 00:00:00 GMT
Link: <https://olivares.ai/docs/how-to/migrate-example/>; rel="sunset"
```
Удалите — не раньше даты вывода из эксплуатации, обычно со следующей мажорной версией API.

Минимальные окна поддержки (анонс депрекации → вывод из эксплуатации):

Уровень	Минимальное окно
stable	24 месяца
beta	12 месяцев

Эти окна обеспечиваются тестами против таблицы объявлений: запись, вывод из эксплуатации которой нарушает окно её уровня или которая указывает на несуществующий маршрут, не собирается.

Для gRPC депрекация выражается опцией protobuf deprecated (которая проявляется в сгенерированном коде) плюс те же окна; протокольные контракты в остальном заморожены, и buf breaking отклоняет несовместимые правки сразу.

Что видят клиенты

Terraform-провайдер — выдаёт tflog WARN (метод, эндпойнт, даты, руководство) один раз на уникальный метод и путь запроса за запуск, когда ответ control plane несёт сигнал депрекации (депрекированный параметризованный маршрут предупреждает один раз на каждый затронутый ресурс) и отправляет версионированный User-Agent, так что использование депрекированного клиента можно атрибутировать на стороне сервера.
Go SDK — выводит DeprecationNotice один раз на эндпойнт (по умолчанию: предупреждение slog; переопределяется через WithDeprecationHandler). Депрекированные операции несут Go-маркеры // Deprecated:, так что редакторы и staticcheck помечают их на этапе разработки.
Python SDK — одно DeprecationWarning на эндпойнт (или ваш колбэк on_deprecation); депрекированные операции помечены в docstring’ах.
TypeScript SDK — одно console.warn на эндпойнт (или ваш колбэк onDeprecation); депрекированные операции несут JSDoc @deprecated.

См. также

Справочник REST API — сам стабильный контракт
Использование клиентских SDK
Сборка и поставка коннектора — контракт и жизненный цикл SDK коннекторов
Управление как кодом (Terraform)
Модуль XIX — собственный API + управление как кодом
Шина событий (AsyncAPI 3.0)
Честность и ограничения