Я меняю API так, будто старый клиент появится завтра

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

Хороший API-контракт — это не только описание полей. Это обещание о том, как система будет вести себя при обычных и ошибочных сценариях. Нарушить его можно не только удалением метода. Иногда достаточно поменять формат даты, сделать необязательное поле обязательным или иначе отсортировать список.

Изменение начинается с вопроса: что обещано

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

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

Добавить обычно безопаснее, чем заменить

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

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

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

Что проверить до выпуска

Я бы начал с нескольких живых примеров запросов: типичный, минимальный, с ошибкой, с повторной отправкой и с данными старого формата. Это не заменяет тесты, но даёт им смысл. Особенно важно проверить не только ответ сервера, но и действие после него: создался ли документ, не задвоился ли заказ, не исчезло ли важное уведомление.

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

Наблюдаемость — часть контракта

После выпуска важно видеть не только общую ошибку «500». Нужны идентификатор операции, версия клиента, причина отказа и путь, по которому запрос прошёл. Иначе при первом сбое команда начинает собирать историю по чатам и логам, а клиент ждёт решения.

Я считаю полезным посмотреть на одну критичную операцию от входящего запроса до результата в соседней системе. Это практичнее, чем любоваться набором графиков. Такой подход подробно раскрыт в заметке о наблюдаемости по пути операции.

Данные старого формата не исчезают по команде

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

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

Совместимость — это не только поля ответа

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

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

Кому принадлежит ошибка

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

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

Почему документация не должна отставать

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

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

Как выпускать без героизма

Я предпочитаю выпускать контракт маленькими шагами. Сначала новая возможность доступна ограниченной группе или одному внутреннему клиенту. Затем появляются метрики и журнал ошибок. Только после этого старый путь объявляют устаревшим. Если в любой момент наблюдения становятся хуже, есть понятный шаг назад.

Такой выпуск не медленнее. Он экономит время, которое обычно уходит на ночной поиск отличий, ручные исправления и объяснения, почему «ничего существенного не меняли». Архитектурные допущения лучше фиксировать до релиза: иначе они становятся скрытым риском.

Практический список перед изменением

• Назовите клиентов и их критичные сценарии.
• Отделите расширение контракта от несовместимой замены.
• Проверьте повторы, ошибки и старые форматы данных.
• Добавьте способ увидеть одну операцию целиком.
• Назначьте владельца разбора и путь отката.

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