STRUCTUREцифровые системыОбсудить проект
НОВОСТЬ · Engineering

Как менять поля API без поломки старых клиентов: переходный контракт

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

Главное

В материале на Хабре рассматривается моделируемый пример с заказами, а не реальная авария в известном сервисе. Приложение, кабинет партнёра и бухгалтерская выгрузка продолжают использовать `customer_id`, тогда как разработчики хотят перейти на `buyer_id`. Изменение модели данных выглядит простым, но для публичного интерфейса это два разных контракта: установленное мобильное приложение нельзя обновить одновременно с сервером.

Безопасный переход начинается с расширения серверного интерфейса. В ответе GET временно присутствуют оба имени с одним значением, а обработчик PATCH принимает старое и новое поле, сохраняя один внутренний идентификатор. Если клиент прислал одновременно разные значения, запрос следует отклонить, а не угадывать приоритет. Отсутствующий ключ, пустая строка и явный `null` также должны иметь заранее описанное поведение.

Подробности

Обновлять OpenAPI-схему нужно после того, как переходный сервер действительно научился обслуживать оба варианта. Атрибут `deprecated` сообщает об устаревании прежнего имени, но не преобразует запросы автоматически. Поэтому отдельно проверяют входные и выходные схемы, документацию, генерацию SDK и клиентов со строгим разбором JSON: даже добавление нового свойства в некоторых реализациях может оказаться несовместимым.

Потребителей переводят по одному, проверяя реальные клиентские сборки против нового сервера и наблюдая за использованием имён во входящих запросах. Однако статистика PATCH не показывает, какое поле программа читает из ответа GET. В план проверки приходится включать контракты потребителей, вебхуки, пакетные выгрузки, события и редкие задания, которые могут пользоваться прежней схемой независимо от основного приложения.

Что это меняет

Сокращать ответ до одного `buyer_id` разумно лишь после подтверждённого перехода всех поддерживаемых интеграций и проверки отката. Отсутствие старых запросов за короткий срок не доказывает, что никто больше не читает `customer_id`. Единственное каноническое значение внутри сервера помогает вернуть выдачу обоих имён без обратной миграции данных, если после релиза обнаружится забытый потребитель.

Первоисточник

Материал подготовлен STRUCTURE по открытой публикации Habr. Текст и иллюстрации первоисточника не воспроизводятся целиком.

Читать исходную новость целиком ↗