Как написать гайд по миграции API

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

Что такое гайд по миграции API?

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

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

Когда изменению нужен гайд по миграции, а не просто запись changelog?

Когда между старым и новым поведением больше одного шага, или когда изменение затрагивает достаточно точек вызова, чтобы вызывающей стороне было полезнее проработанный пример, чем описание. Что такое несовместимое изменение, и как его выпустить разбирает тест на то, является ли изменение несовместимым; если ответ да, второй вопрос — это однострочная правка или настоящая миграция. С переименованным полем вызывающая сторона может справиться просто по записи changelog. Изменение в аутентификации, пагинации или обработке ошибок почти всегда заслуживает гайда, потому что правильный замещающий код не очевиден из однопредложенческого описания.

Что должен содержать гайд по миграции?

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

## Миграция полей валюты с float на integer (v3.0.0)

До:
  { "amount": 19.99 }

После:
  { "amount": 1999 }  // наименьшая единица валюты (центы)

Что меняется: `amount` теперь целое число в наименьшей единице
валюты аккаунта. Код, читающий `amount` как float, будет читать
значение в 100 раз больше начиная с 1 октября 2026 года.

Проверка: после миграции списание $19.99 должно читаться как
`amount: 1999`, а не как `amount: 19.99`.

График: v2 продолжает возвращать float до 15 января 2027 года. v3
возвращает целые числа с момента запуска. Обе версии сейчас активны.

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

Кто должен его писать, и когда?

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

Как это связано с версионированием и changelog API?

Напрямую: гайд по миграции — это подробная версия того, что запись MAJOR в semantic versioning и вашем changelog только резюмирует в одном предложении. Запись changelog говорит, что изменение несовместимо, и примерно что изменилось; гайд по миграции — это ссылка, которую должна нести эта запись. Changelog API: что публиковать и кто это читает перечисляет гайд по миграции как один из пяти документов, которые ведёт API, каждый отвечает на свой вопрос; это тот, что отвечает на «как реально перейти от A к B», и он заслуживает собственной страницы именно потому, что этот ответ обычно слишком длинный для записи changelog.

Как долго гайд по миграции должен оставаться опубликованным?

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

FAQ

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

Должен ли гайд по миграции жить с документацией API или в changelog? С документацией, со ссылкой из записи changelog. Запись — это то, что подписчица видит первым; гайд — это то, что нужно, как только она решила действовать, и место ему рядом с справочными материалами, которые вызывающая сторона уже использует.

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

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

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

По теме на changeloop: Документация для разработчиков, Примеры changelog