Интерфейс тестируется легко: поменял кнопку, половина пользователей видит новый цвет, метрика решает. API живет строже: за каждым вызовом стоит интеграция, чей код меняется без ведома её автора, и эксперимент на уровне интерфейса программ это игра с чужими договорённостями. Версионирование и эксперименты в API это дисциплина смены контрактов: как вводить новое поведение, не ломая старых клиентов, как делить трафик на варианты, не мигая результатом, и как честно провожать устаревшие версии, не устраивая инцидент в два часа ночи.
Ниже разобраны слои этой дисциплины: отличие серверных экспериментов от интерфейсных, способы записи версии в вызов, липкое распределение вариантов, контрактная совместимость, теневой прогон и канарейка, метрики на вариант и церемониал отключения старого. С кодом, стандартными заголовками и правилами, которые экономят репутацию API перед теми, кто на нём строит.
Зачем экспериментировать на уровне API и чем это отличается от тестов интерфейса
Эксперимент на уровне интерфейса меняет то, что видит человек в своём браузере, и откатывается за минуту. Эксперимент на уровне API меняет то, чем пользуется чужой код, часто без интерфейса вовсе: фоновая интеграция, сервер партнёра, мобильное приложение полугодовой давности. Разница фундаментальна: у интерфейсного изменения аудитория управляема, у серверного изменения аудитория это все, кто когда-либо вызвал эндпоинт, включая версии клиентов, которых вы не видели.
Отсюда главное отличие: эксперименты в API обязаны сохранять контракт. Вариант поведения может отличаться скоростью ответа, структурой содержания внутри обещанных полей, алгоритмом подсчёта, но не обязан нарушать схему. Новый вариант с новым полем это расширение, а вариант с другим типом существующего поля это уже смена мажорной версии, и это различие проходит через всю статью.
Второе отличие это контроль: серверный эксперимент назначается на стороне сервера, и клиент не может ни подсмотреть, ни переключить. Для чувствительных вещей, алгоритмы ранжирования, тарификация, антизлоупотребления, серверное назначение единственно честное, и API это естественная площадка таких экспериментов.
Третье отличие это стоимость ошибки: интерфейсный провал виден сразу и локально, серверный провал расходится по интеграциям и всплывает в чужих системах мониторинга. Именно поэтому далее половина статьи про то, как выпускать вариант так, чтобы его можно было тихо вернуть.
Способы версионирования путь заголовок параметр и их последствия
Путь с номером версии в самом URI это самый заметный способ: старая версия остаётся на старом пути, новая живёт на новом, и клиент выбирает явно. Достоинство в видимости: версия читается в логах, в мониторинге, в документации и в переписке с интеграторами. Недостаток в косности: каждая мажорная версия это копия поверхности, которую приходится поддерживать, и число поддерживаемых версий растёт быстрее, чем хочется.
Заголовочное версионирование прячет версию в заголовке запроса: акцепт-типы с параметром версии или собственный заголовок клиента. Вызов остаётся на одном пути, инфраструктура не плодит копий, а клиент согласовывает версию явно при каждом обращении. Цена: версия невидима в простых логах без пробора заголовков, и документация обязана компенсировать эту невидимость.
function version(versions) {
return (req, res, next) => {
const requested = req.get("Accept") ?? "";
const match = requested.match(/version=(\d+)/);
req.version = match
? Number(match[1])
: Math.max(...versions);
next();
};
}Параметр строки запроса это третий классический способ, живой и для экспериментов удобный, но для мажорных версий слабый: параметр теряется при копировании вызовов, и половина трафика молча падает на версию по умолчанию. Смешение способов не запрещено, но выбор основного диктуется культурой потребителей: публичные API с долгоживущими интеграторами чаще живут на путях, продукты со своей клиентской экосистемой на заголовках.
Семантические рамки поверх любого способа: мажорная версия это право ломать, минорная это обещание не ломать, и патч это исправления без нововведений. Экспериментальные флаги живут внутри минорной версии и не являются версиями вообще, и это разделение проговаривается в политике API до первого эксперимента, а не после первой путаницы.
Липкие корзины назначение варианта без мигания результата
Эксперимент имеет смысл, только если пользователь последовательно видит один вариант, и на уровне API пользователем часто выступает не человек, а интеграция или ключ приложения. Назначение по хешу от устойчивого идентификатора решает вопрос тождества: одинаковый идентификатор всегда даёт одинаковую корзину, и вызовы из разных мест одной интеграции попадают в один вариант без центрального хранилища.
function bucket(userId, experiment, variants) {
const h = sha256(`${userId}:${experiment}`);
const n = parseInt(h.slice(0, 8), 16);
return variants[n % variants.length];
}Солью против корреляции между экспериментами служит имя эксперимента в хеше: два эксперимента с одинаковыми пользователями не обязаны делить людей на корзины одинаково, и смена соли перетасовывает распределение независимо. Доля вариантов задаётся с запасом статистики и сдержанностью риска: половина на половину для быстрых ответов, узкая полоска для опасных новинок.
Липкость на время живёт с исключением: по требованию закона или по гарантии отладки корзину можно переопределить явно, и переопределение журналируется как отступление от распределения. Без таких исключений поддержка не разбирает жалобы, но и не доверяет распределению, и честная лазейка с журналом лучше тихих заглушек в коде.
Смена распределения это отдельная церемония: перенос пользователей между вариантами середины эксперимента загрязняет метрики, и потому перетасовка делается либо с началом нового эксперимента, либо с фиксированной записью о моменте смены, после которой сравниваются только периоды после смены. Плавный перелив корзин без журнала это способ обнулить смысл недель наблюдений.
Стабильность контракта аддитивность и совместимость вариантов
Правило аддитивности звучит коротко: внутри мажорной версии новое поле можно добавить, существующее поле трогать нельзя. Экспериментальные варианты обязаны жить в этих рамках, и отличие вариантов держится в содержимом полей, в скорости, в алгоритмах, но не в форме ответа. Клиент, написанный против контракта, обязан пережить любой вариант без единой правки, и это критерий честности эксперимента на API.
Варианты с расширениями помечаются явно: поле с описанием варианта в ответе или заголовок с именем флага, и потребитель при желании видит, в какой он корзине. Скрытые различия работают до первого обращения в поддержку, где интегратор честно не понимает, почему у него ответ отличается от соседского, и прозрачность экономит часы разбирательств.
Контрактные тесты гоняются на каждый вариант: одна и та же сборка проверяет схему ответов каждой ветки, и расхождение схемы между вариантами останавливает релиз. Тесты на содержимое могут отличаться по условию, тесты на форму обязаны быть зелёными всегда, и это различие встроено в конвейер, а не в память ревьюеров.
Совместимость клиента проверяется на старых версиях сборок: минорная версия с экспериментами обязана работать с клиентом позапрошлого релиза, и стенд со старыми версиями входит в определение готовности каждого эксперимента. Это скучнее, чем звучит, и именно такая скука отделяет взрослый API от эффектной демки.
Тень и канарейка как проверить версию без доверия пользователей
Теневой прогон это репетиция без последствий: копия рабочего трафика уходит в новую версию, ответы сравниваются, пользователю возвращается результат старой версии. Тень снимает страх первого контакта новой версии с реальными значениями, потому что первое знакомство происходит на дубле, и падение тени не трогает ни одного клиента.
Сравнение в тени бывает разным: побайтовое для простых ответов, структурное с допуском для полей с временем и случайностью, и выбор глубины сравнения зависит от терпимости интеграторов к отличиям. Расхождения журналируются с указанием ветки, и утренний разбор тени это дешёвая замена ночному инциденту.
Канарейка это первая смена живого трафика: один процент вызовов обслуживается новой версией, и метрики ошибки и задержки смотрятся с усиленным вниманием. Пороги автоматического возврата настраиваются заранее, и канарейка без автомата возврата это не осторожность, а храбрость с другим словом.
Канареечная подача сочетается с экспериментальными корзинами: канарейка решает вопрос годится ли версия вообще, эксперимент решает вопрос лучше ли новое поведение. Смешение этих вопросов в один переключатель это распространённая ошибка, и разделение релиза от эксперимента проговаривается в терминологии команды, чтобы каждый понимал, что именно он сейчас включает.
Метрики вариантов ошибки задержка и принятие новой версии
Минимальный набор метрик варианта это тройка: доля ошибок, задержка ответов, и доля населения. Ошибки меряются по статусам и по внутренним отказам, задержка по перцентилям, а не по среднему, и население по числу уникальных ключей, а не по числу вызовов. Тройка режется по вариантам на каждом экране мониторинга, и любой график без деления по варианту в эксперименте это полграфика.
Принятие новой версии отдельная дисциплина для мажорных релизов: доля вызовов по версиям, скорость переезда интеграторов, обращения в поддержку с упоминанием версии. Принятие публикуется: страница с долями версий и датами заката работает на доверие интеграторов сильнее любых писем, потому что цифры честнее обещаний.
Статистическая честность для серверных экспериментов та же, что для любых других: заранее посчитанный объём наблюдений, заранее выбранная метрика решения, запрет подглядывания и запрет остановки по первому красивому утру. API дарит роскошь точных событий на стороне сервера, и этой роскошью пользуются вместо приблизительных клиентских сигналов.
Журнал экспериментов завершает метрики: имя, доля, период, решение, ссылка на разбор, и запись о том, что стало с флагом. Через год журнал отвечает на вопрос, почему поле отвечает именно так, и отсутствие журнала превращает каждый такой вопрос в археологию.
Закат старой версии расписание заголовки и дисциплина отключения
Отключение старой версии это процесс, а не событие пятницы. Объявление о закате живёт в стандартных заголовках ответа старой версии: время устаревания и заголовок предупреждения, и интеграторы с автоматикой читают их раньше, чем письма. Письма, однако, никто не отменял, и дублирование каналов оповещения это часть церемониала, а не расточительность.
Расписание заката растянуто: объявление за месяцы, предупреждения по нарастающей, доля ошибок на заголовках не растёт до последней ступени, и полное отключение наступает после периода зеркальных ошибок. Каждая ступень публикуется, и интегратор строит переезд по календарю, а не по слухам. Резкое отключение живой версии это выбор дешёвого решения за счёт чужих выходных, и репутация API платит по этому счёту годами.
Мосты переезда обязательны: таблица соответствия старых и новых полей, руководство на полстраницы, и работающий пример вызова в новой версии. Интегратор без моста уходит в похождение по исходникам, и каждый час его похождения это будущий тикет поддержки, который мог не случиться.
Порядок внедрения экспериментов и версий в API свёрнут в короткую лестницу:
- выбрать способ записи версии и опубликовать политику мажоров и миноров;
- развести релизный поезд и экспериментальные флаги в терминах команды;
- включить липкое распределение по хешу с солью имени эксперимента;
- гонять контрактные тесты на каждый вариант в конвейере;
- выпускать поведение через тень и канарейку с автоматом возврата;
- мерить тройку ошибок, задержек и населения по вариантам публично;
- закрывать старые версии по расписанию с заголовками и мостами.
API, который экспериментирует, выглядит внешне неподвижно: те же пути, та же схема, те же заголовки, и лишь номера версий в расписании заката выдают движение внутри. Именно эта неподвижность снаружи и дисциплина внутри и составляют разницу между API, на который интеграторы полагаются годами, и API, о котором вспоминают с содроганием при каждом письме о поддержке.