Сервис закрыт, а его API кто-то продолжает дёргать: как отключать по-человечески

MAATRIX

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

Почему API не закрывается вместе с сервисом

У фронтенда и у API разная механика смерти. Когда сайт закрывается, живые пользователи это видят сразу: страница не открывается, приходит письмо, интерфейс замолкает. У API аудитория другая — это не люди, которые заходят и замечают изменения, а код, который был написан один раз и с тех пор работает без присмотра.

Три типичных источника трафика, который продолжает идти к давно закрытому API:

• Интеграции, о которых все забыли. Партнёр когда-то подключил ваш API к своей системе — синхронизация каталога, приём заказов, вебхук на изменение статуса. С тех пор прошло два-три года, человек, который настраивал интеграцию, мог уже сменить работу, а сама интеграция продолжает исправно дёргать эндпоинт по расписанию, потому что её никто не трогал и она не давала повода ей заняться.
• Мобильные приложения без принудительных обновлений. Если приложение публиковалось в сторах и не имеет механизма форс-апдейта, часть пользователей годами сидит на старой версии. Такое приложение может обращаться к вашему API даже после того, как в сторе давно висит новая версия или само приложение снято с публикации — установленная копия на телефоне не знает и не спрашивает, актуален ли ещё бэкенд.
• Кешированные и захардкоженные клиенты. Скрипт на сервере клиента, однажды написанный интегратором на фрилансе, cron-задача, которая раз в сутки синхронизирует данные, тестовый стенд у бывшего партнёра, который так и остался «на всякий случай» с продовым ключом API. Все они объединены одним: код написан, работает, никто в него давно не заглядывал.

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

Шаг 1. Объявите дату закрытия заранее, если знаете, кому это адресовать

Первое и самое дешёвое, что можно сделать — назвать конкретную дату полного отключения и сообщить о ней заранее, а не постфактум.

Если у вас есть список известных интеграторов — партнёров, которым выдавались API-ключи, компаний, с кем заключались договоры на доступ к API, авторов приложений, которые официально запрашивали доступ — напишите им лично. Не общий пресс-релиз, а прямое письмо на контакт, который был в договоре или в заявке на ключ: «API сервиса будет отключён {дата}, у вас есть {срок} на миграцию, вот контакт по вопросам». Персональное уведомление конкретному человеку почти всегда работает лучше, чем публичный анонс, который тот же человек может просто не увидеть.

Если публичного списка интеграторов нет или он неполон — по крайней мере зафиксируйте дату отключения в документации API, если она ещё доступна, и в самом теле ответа API уже на этом этапе (подробнее — в шаге 2). Дата должна быть конкретной, а не «в ближайшее время» или «скоро» — расплывчатая формулировка не даёт автоматическому клиенту и его разработчику ничего, на что можно среагировать: непонятно, стоит чинить интеграцию сегодня или можно отложить на полгода.

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

Шаг 2. Постепенная деградация вместо мгновенного обрыва

Самая частая ошибка при закрытии API — выключить сервер одним днём. Для клиента, который делал запрос вчера и получал 200 OK, а сегодня получает таймаут или Connection refused, это выглядит абсолютно неотличимо от аварии. Разработчик на той стороне не знает, что сервис закрылся официально — он видит только то, что раньше работало, а теперь нет, и первая гипотеза почти всегда «у нас что-то сломалось», а не «у них закрылся сервис».

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

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

HTTP/1.1 200 OK
X-API-Deprecation: true
X-API-Sunset-Date: 2026-11-01
Warning: 299 - "This API will be permanently discontinued on 2026-11-01. See https://example.com/api-sunset for details."

Заголовок Sunset — часть черновика стандарта RFC 8594, который многие API уже используют именно для этой цели, поэтому его понимают не только люди, но и часть автоматизированных инструментов мониторинга API.

Этап 2 — ошибка с понятным сообщением вместо разрыва соединения. Ближе к дате отключения или сразу после неё замените реальный ответ на осмысленную ошибку — не 500 без текста и не обрыв TCP-соединения, а код и тело, которые прямо называют причину:

HTTP/1.1 410 Gone
Content-Type: application/json

{
  "error": "service_discontinued",
  "message": "Этот API закрыт с 1 ноября 2026 года и больше не отвечает. Подробности и контакт: https://example.com/api-sunset",
  "sunset_date": "2026-11-01"
}

Код 410 Gone для этого случая подходит лучше, чем 404 Not Found или 503 Service Unavailable: 404 формально означает «такого ресурса не существует», что двусмысленно (может, опечатка в пути?), а 503 в HTTP-семантике означает временную недоступность — клиент по спецификации имеет право повторить запрос позже. 410 прямо говорит: ресурс был, теперь его нет и не будет, повторные попытки бессмысленны. Многие HTTP-клиенты и SDK умеют логировать текст ошибки целиком — значит, кто-то, кто мониторит логи своей интеграции, увидит не просто код, а человекочитаемую причину и ссылку, куда идти за подробностями.

Этап 3 — полное отключение. Только после того как этап 2 отработал какое-то время (недели, а не дни — чтобы дать шанс увидеть ошибку тем, кто проверяет логи не каждый день), можно переходить к настоящему выключению инфраструктуры. К этому моменту почти все автоматические клиенты уже получили однозначный сигнал и либо отреагировали, либо как минимум залогировали причину, а не гадают, что случилось.

Такая ступенчатая схема стоит немного лишней инженерной работы на первых двух этапах, но экономит гораздо больше времени — как вашего, если начнут писать в старую техподдержку с вопросом «у вас всё упало?», так и чужого, потраченного на бесплодную отладку несуществующей проблемы.

Шаг 3. Мониторинг перед финальным отключением — кто ещё реально стучится

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

Минимальный набор, который стоит собрать за последние 2-4 недели перед финальным отключением:

# частота обращений по IP/user-agent — веб-сервер nginx
awk '{print $1, $NF}' /var/log/nginx/api_access.log | sort | uniq -c | sort -rn | head -30

# то же самое, но с разбивкой по API-ключу, если он логируется отдельным полем
grep 'api_key=' /var/log/nginx/api_access.log | \
  grep -oP 'api_key=\K[^&\s]+' | sort | uniq -c | sort -rn | head -30

# распределение по эндпоинтам — какие ручки ещё живы
awk '{print $7}' /var/log/nginx/api_access.log | cut -d'?' -f1 | sort | uniq -c | sort -rn | head -20

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

Если найдётся источник с явно регулярным паттерном и при этом определяемым владельцем — по IP-диапазону, известному user-agent, привязке к конкретному API-ключу, который выдавался конкретной компании — стоит попытаться связаться напрямую, даже если формальный анонс уже был разослан всем. Люди пропускают письма, письма попадают в спам, контакт в договоре мог смениться. Дополнительное личное сообщение конкретному источнику трафика, который явно ещё зависит от API, — недорогой шаг, который иногда предотвращает несправедливо неприятный сюрприз для чужого бизнеса.

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

Шаг 4. После даты отключения — заглушка вместо пустоты

Когда объявленная дата наступила и вы гасите последнюю инфраструктуру, у вас есть выбор, что оставить на месте бывшего API: либо ничего (домен просто перестаёт резолвиться или сервер перестаёт принимать соединения), либо простую статическую страницу с объяснением.

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

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate     /etc/letsencrypt/live/api.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.example.com/privkey.pem;

    location / {
        default_type application/json;
        return 410 '{"error":"service_discontinued","message":"Этот API закрыт с 1 ноября 2026 года и больше не работает. Подробности: https://example.com/api-sunset","sunset_date":"2026-11-01"}';
    }
}

Такой конфиг можно держать месяцами на минимальном VPS — он почти не потребляет ресурсов, поскольку не делает ничего, кроме отдачи одного статического ответа, зато принципиально меняет то, что видит запоздавший клиент. Разница между «домен не резолвится» и «домен отвечает понятным JSON с датой закрытия» для разработчика на другом конце — это разница между часом бесплодной отладки DNS и сетевых проблем и одной минутой чтения сообщения об ошибке.

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

Текст в заглушке и в предупреждающих заголовках полезен настолько, насколько он конкретен — код 410 без пояснений говорит «что-то не так», но не говорит, что именно. В тело ответа стоит класть четыре вещи: прямую формулировку, что сервис закрыт навсегда, а не временно недоступен (это решает, будет ли разработчик ретраить запросы); дату закрытия; ссылку на страницу с подробностями, если она есть; и контакт для вопросов, актуальный хотя бы первые недели после отключения. Пример из nginx-конфига выше уже покрывает все четыре пункта — этого достаточно, растягивать сообщение дальше не нужно.

Общий принцип: у «ничьего» API есть люди на другом конце

Легко думать про API как про технический интерфейс между системами — но за каждым запросом, идущим по расписанию годами, когда-то стоял конкретный человек, который его настроил. Этого человека, возможно, давно нет в компании, но код, который он написал, продолжает работать — и когда он перестаёт получать ожидаемый ответ, разбираться с этим приходится кому-то живому: инженеру поддержки на стороне партнёра, разработчику, к которому прибежали с вопросом «почему всё упало», иногда просто человеку, который открывает мобильное приложение и видит бесконечную загрузку без объяснений.

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

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

Частые вопросы