{
  "index": 114,
  "slug": "editorial-2024-11-practice-deprecation",
  "title": "Депрекация API: как не удалить контракт вместе с неизвестным потребителем",
  "excerpt": "Дата Sunset не доказывает, что API больше никто не вызывает. Разбираем consumer map, границы доказательств и removal gate, который останавливает опасное удаление.",
  "contentHtml": "<p>В задаче стоит дата: после 3 февраля путь <code>/v1/posting</code> удалят. Наступает день релиза. В графике вызовов пусто, в OpenAPI уже стоит <code>deprecated: true</code>, а команда не видит владельца старого клиента. Кто-то открывает pull request и удаляет обработчик. Через час внешний интегратор получает 404 или 410. У команды нет ответа на три вопроса: кому сообщили, какой контракт предложили взамен и что именно доказало безопасность удаления.</p>\n<p>Это не редкий сбой календаря. Дата задаёт границу планирования, но не подтверждает отсутствие потребителей. Пустой график описывает только выбранный инструмент, маршрут, период и набор сигналов. Пометка в схеме сообщает о жизненном цикле операции, но не мигрирует SDK. Реальная депрекация должна разделять объявление, миграцию и удаление.</p>\n<p><strong>Тезис:</strong> не удаляйте устаревший API по дате или одному зелёному индикатору. Сначала ограничьте одну операцию, составьте consumer map и укажите границу каждого доказательства. Если остался активный или неизвестный потребитель, автоматическое удаление запрещено. Для полностью подготовленного случая открывают отдельный human review, а не превращают ревью депрекации в незаметный production change.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<table><caption>Быстрый разбор перед изменением контракта</caption><thead><tr><th>Симптом</th><th>Причина</th><th>Проверка</th><th>Действие</th></tr></thead><tbody><tr><td>Есть дата удаления, но нет списка владельцев</td><td>Дедлайн приняли за доказательство последнего consumer</td><td>Проверить contract, scope, owner и evidence boundary</td><td>Заблокировать removal и открыть consumer map</td></tr><tr><td>В telemetry нет запросов</td><td>Пустой сигнал ограничен периодом, sampling, proxy или credential boundary</td><td>Записать инструмент, окно, маршрут и слепые зоны</td><td>Назвать результат <code>not observed in this scope</code>, а не «никто не использует»</td></tr><tr><td>В OpenAPI стоит <code>deprecated: true</code></td><td>Декларацию смешали с миграцией</td><td>Найти replacement, владельца и путь перехода</td><td>Опубликовать notice и migration guide</td></tr><tr><td>Все известные клиенты мигрировали</td><td>Named rows приняли за полную population</td><td>Проверить unknown scope и остаточный риск</td><td>Разрешить только отдельный human review</td></tr></tbody></table>\n<h2>Сначала зафиксируйте, что именно устаревает</h2>\n<p>Фраза «удаляем v1» слишком широкая. Она может означать один HTTP route, несколько методов, SDK-функцию, callback или весь набор ресурсов. Выберите одну operation. Запишите HTTP method, URI template, operationId, request и response shape, authentication boundary и replacement. Если новый путь меняет семантику, сравните не только URL. Проверьте idempotency key, коды ошибок, pagination, ретраи и правила авторизации.</p>\n<p>Такой scope снижает риск ложного согласия. Владелец сервиса может подтвердить удаление одного метода, но не всего API. Владелец SDK может выпустить новую функцию, но не контролировать старые бинарные клиенты. Внешний потребитель может получать notice через документацию, но не читать вашу схему. Контракт, владелец и канал объявления должны совпадать по scope.</p>\n<p>OpenAPI помогает объявить операцию устаревшей. Поле <code>deprecated</code> отвечает на вопрос «рекомендуется ли эта операция дальше?». Оно не отвечает на вопросы «кто вызывает её сейчас?» и «может ли replacement принять тот же сценарий?». Поэтому schema и consumer map — разные артефакты. Один сообщает о намерении. Второй связывает намерение с людьми, зависимостями и проверками.</p>\n<h2>Consumer map хранит не только найденных клиентов</h2>\n<p>Минимальная строка карты содержит consumer, класс сведения, contract, owner, migration path, deadline, announcement и evidence boundary. Не скрывайте неизвестность. Строка <code>unknown consumer</code> честнее, чем пустая таблица. Она означает, что область ещё не замкнута и автоматический removal нельзя считать безопасным.</p>\n<table><caption>Учебная карта для одной операции</caption><thead><tr><th>Потребитель</th><th>Сведение</th><th>Владелец и переход</th><th>Граница доказательства</th></tr></thead><tbody><tr><td><code>synthetic-web-checkout</code></td><td>source usage</td><td><code>synthetic-checkout-owner</code>; fixed v1 call → fixed v2 contract</td><td>Учебная строка, не результат поиска кода</td></tr><tr><td><code>synthetic-sdk-package</code></td><td>declared dependency</td><td><code>synthetic-sdk-owner</code>; выпустить v2 SDK surface</td><td>Учебная запись зависимости, не package inventory</td></tr><tr><td><code>synthetic-unknown-integrator</code></td><td>unknown consumer</td><td><code>synthetic-api-owner</code>; сохранить notice и ограничить scope</td><td>Не customer list и не доказательство отсутствия вызовов</td></tr></tbody></table>\n<figure><img src=\"/assets/editorial/2024/deprecation-2024-consumer-map.svg\" alt=\"Consumer map для устаревшего API: контракт связан с потребителем, владельцем, миграцией, дедлайном, объявлением и границей доказательства; неизвестный потребитель блокирует автоматическое удаление\"><figcaption>Карта разделяет известные зависимости и unknown scope. Все имена и даты на схеме учебные.</figcaption></figure>\n<p>Разные классы evidence нельзя складывать в один count. Source usage показывает вызов в разрешённой области исходного кода. Declared dependency показывает объявленную связь пакета, схемы или SDK. Observed traffic показывает запросы в конкретном маршруте и окне. Authorization показывает, какой credential class имеет право обратиться. Ни один класс сам по себе не доказывает полную population клиентов.</p>\n<p>Например, пустой access report может не видеть запросы через gateway, другой hostname, старый credential или редкий batch. Кодовый поиск может не найти вызов, спрятанный в сгенерированном клиенте или внешнем binary. Manifest может хранить уже неиспользуемую зависимость. Поэтому рядом с каждой строкой пишите не только результат, но и то, чего он не доказывает.</p>\n<h2>Объявление, Sunset и удаление — разные границы</h2>\n<p>Уведомление должно дать потребителю понятный replacement, владельца и ссылку на инструкцию. HTTP-заголовок Deprecation может сообщить, что ресурс устарел или станет устаревшим. Sunset сообщает ожидаемую будущую недоступность ресурса. Оба сигнала улучшают обнаруживаемость решения. Они не заставляют клиент мигрировать и не подтверждают, что клиент получил, понял или применил notice.</p>\n<p>Сохраните в записи lifecycle отдельные поля. Дата депрекации описывает статус контракта. Sunset boundary описывает ожидаемое изменение доступности. Removal gate описывает условия допуска к отдельному изменению. Не называйте Sunset жёсткой гарантией: RFC 8594 формулирует его как указание на ожидаемую недоступность, а не как доказательство фактического поведения каждого клиента.</p>\n<pre><code>{\n  \"contract\": \"synthetic-ledger-v1-posting-path\",\n  \"owner\": \"synthetic-ledger-owner\",\n  \"replacement\": \"synthetic-ledger-v2-posting-path\",\n  \"deprecationDate\": \"synthetic-2024-11-04\",\n  \"sunsetBoundary\": \"synthetic-2025-02-03\",\n  \"announcement\": \"synthetic-public-deprecation-page\",\n  \"unknownConsumerRule\": \"unknown blocks automatic removal\",\n  \"restoreBoundary\": \"stop proposal before a real removal change\"\n}</code></pre>\n<p>Код выше — учебный объект. Он не является production-конфигурацией, не содержит реальную дату, токен, route table или список клиентов. Его задача — показать обязательные связи. Если у replacement нет владельца или у unknown нет границы проверки, объект не готов к removal review.</p>\n<h2>Removal gate проверяет отрицательные условия</h2>\n<p>Хороший gate формулируют как список причин не удалять. Есть active consumer — остановиться. Есть unknown scope без принятого остаточного риска — остановиться. Replacement не сохраняет важную семантику — остановиться. Notice не связан с affected scope — остановиться. Restore boundary не описана — остановиться. Ранняя дата не компенсирует ни один из этих пробелов.</p>\n<p>Слово «мигрировал» тоже требует проверки. Оно должно означать, что конкретный consumer получил replacement, проверил совместимость и больше не зависит от старой операции в согласованной границе. Если строка лишь помечена как migrated в таблице, это статус документа, а не runtime evidence. Оставьте исходный тип сведения и ссылку на проверку.</p>\n<p>Если перед удалением найден active consumer, не меняйте одновременно route, authorization, документацию и fallback. Остановите proposal. Зафиксируйте конфликт, сохраните текущую compatibility boundary и назначьте владельца миграции. Если неизвестный потребитель остаётся, владелец должен выбрать одно из трёх действий: сузить разрешённую проверку, продлить совместимость или принять residual risk отдельным решением.</p>\n<h2>Порядок действий</h2>\n<ol><li><strong>Сузьте scope.</strong> Назовите одну operation: method, URI, operationId, request, response и authentication boundary.</li><li><strong>Опишите replacement.</strong> Сравните семантику, ошибки, idempotency, ретраи и права. Один новый URL недостаточен.</li><li><strong>Соберите consumer map.</strong> Добавьте known rows и отдельную строку unknown, если полнота scope не доказана.</li><li><strong>Назначьте владельцев.</strong> Для каждой строки укажите owner, migration path, дедлайн и доступное объявление.</li><li><strong>Разделите evidence.</strong> Запишите тип сигнала, период, инструмент, область и слепые зоны. Не превращайте «не наблюдалось» в «отсутствует».</li><li><strong>Опубликуйте lifecycle notice.</strong> Свяжите deprecation, Sunset, replacement и migration guide. Проверьте, что ссылка доступна нужным потребителям.</li><li><strong>Проверьте stop conditions.</strong> Active, unknown без решения, несовместимый replacement и отсутствующий restore boundary закрывают gate.</li><li><strong>Откройте отдельный human review.</strong> В нём укажите остаточный риск и точный scope. Только после одобрения создавайте authorized removal change.</li><li><strong>Проверьте результат тем же контрактом.</strong> Отдельно подтвердите, что удаление затронуло только выбранную operation и не изменило соседние пути.</li></ol>\n<h2>Ограничения и отрицательный путь</h2>\n<p>Эта схема не делает неизвестных потребителей видимыми автоматически. Она не заменяет разрешённый source search, анализ access logs, inventory клиентов, review авторизации или проверку replacement в реальной среде. Учебные строки в статье не доказывают наличие или отсутствие клиентов. Они показывают, как сохранить класс риска в модели.</p>\n<p>Не пытайтесь получить «нулевой риск» из одного сигнала. Даже полный на вид отчёт имеет scope: конкретный период, route, credential, sampling и доступность данных. Отрицательный путь должен быть первым классом результата. Если проверка не может замкнуть область, ответ — <code>unknown</code>, а действие — сохранить совместимость или провести отдельное решение с владельцем остаточного риска.</p>\n<p>Restore boundary также ограничивает обещание. Для draft достаточно сказать: proposal остановлен, старый контракт не изменён, черновик удалён. После реального удаления нужен другой план: кто возвращает route, какие schema и credentials ещё совместимы и как проверяется восстановление. Фраза «rollback available» без этих условий не является проверяемым планом.</p>\n<h2>Проверяемый критерий готовности</h2>\n<p>Депрекация готова к отдельному removal review, когда одна operation однозначно названа; replacement имеет владельца и описанную compatibility boundary; каждая известная строка consumer map содержит migration path; unknown scope либо ограничен разрешённой проверкой, либо явно принят владельцем; notice и дедлайн доступны; stop condition и restore boundary записаны. Итоговый вердикт должен быть одним из трёх: <code>block: active</code>, <code>block: unknown</code> или <code>allow human review only</code>. Ни один из них не означает, что endpoint уже можно удалить.</p>\n<p>Проверяемый результат — не пустой график и не дата в календаре. Это воспроизводимая запись, в которой другой инженер видит scope, доказательство, его границу, владельца и причину следующего действия. Если он не может повторить проверку или назвать условие остановки, контракт ещё не готов к удалению.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://spec.openapis.org/oas/v3.1.0.html#operation-object\" target=\"_blank\" rel=\"noopener\">OpenAPI Specification 3.1.0: Operation Object</a> — поле <code>deprecated</code> объявляет операцию устаревшей, но не описывает её потребителей.</li><li><a href=\"https://www.rfc-editor.org/rfc/rfc9745.html\" target=\"_blank\" rel=\"noopener\">RFC 9745: The Deprecation HTTP Response Header Field</a> — официальный формат сигнала о депрекации ресурса и ссылки на дополнительные сведения.</li><li><a href=\"https://www.rfc-editor.org/rfc/rfc8594.html\" target=\"_blank\" rel=\"noopener\">RFC 8594: The Sunset HTTP Header Field</a> — назначение Sunset и его граница как указания на ожидаемую недоступность.</li></ul>"
}