МАРШРУТ
Надёжный API и интеграции
Контракты, идемпотентность, webhook, повторы и управляемая деградация.
Ожидаемый результат
Построить API и интеграции с явными контрактами отказов и повторов.
Проектирование API от схемыСхема API создаётся до реализации и служит общим контрактом для серверов, клиентов, документации и тестов.API VersioningИзменения контракта управляются совместимостью и явными версиями.Единый формат ошибок APIОшибки API передаются в предсказуемой структуре с машинным кодом, описанием, экземпляром и дополнительным контекстом.Problem Details для HTTP APIФормат Problem Details стандартизирует машиночитаемое описание ошибок HTTP без создания отдельной схемы для каждого типа сбоя.Контракт идемпотентности APIAPI явно фиксирует, какие операции можно безопасно повторять и как сервер распознаёт повтор одного логического запроса.Доставка webhook как минимум один разОтправитель повторяет доставку до подтверждения, поэтому получатель обязан допускать дубликаты.Защита webhook от повторного воспроизведенияМетка времени, nonce и окно допустимости не позволяют повторно использовать ранее перехваченный корректный webhook.Экспоненциальная задержка и jitterПовторы должны разноситься во времени, чтобы не усиливать сбой.Circuit BreakerПосле серии сбоев вызовы к зависимому сервису временно прекращаются, чтобы не усиливать отказ.Наблюдаемость границы интеграцииТелеметрия задержки, ошибок, повторов и преобразований именно в точке взаимодействия между системами.