Смена версий API: как не сломать интеграции

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

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

1Уведомление2Реестр3Анализ4Тесты5Переход6Мониторинг

Почему интеграции ломаются тихо

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

Опасность тишины не в отсутствии сигнала тревоги, а в том, что система продолжает производить данные. Пустое поле складывается в отчёте как ноль, значение с изменившимся смыслом ломает сегментацию, потерянная связь вешает запись не на того клиента. К моменту обнаружения задач становится две: починить интеграцию и вычистить данные, испорченные за это время. Вторая почти всегда дольше.

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

Как поставщики обозначают версии

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

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

О чём говорит номер версии и о чём молчит

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

Типы поломок и время их обнаружения

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

Тип поломки	Как обнаруживается	Типичная задержка
Отказ в авторизации	Журнал ошибок, сразу	Часы
Адрес метода удалён	Журнал ошибок, сразу	Часы
Поле удалено, приходит пустым	Нестыковка в отчётах	Недели
Изменился смысл или формат поля	Накопление неверных данных	Недели или месяцы
Ужесточилась квота или лимит	Частичные потери в часы пик	Дни

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

Пока вы не знаете, что у вас есть, план перехода невозможен

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

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

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

Кто получает уведомление

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

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

Тесты: что доказывает тестовая среда, а что нет

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

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

Защитное чтение на своей стороне

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

Самое опасное состояние интеграции — не когда она выдаёт ошибку, а когда она работает неправильно, не выдавая ошибок.

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

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

Мониторинг: заметить поломку должны вы сами

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

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

День перехода: параллельная работа и откат

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

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

Когда не обновляться — правильное решение

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

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

С чего начать

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

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

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