На GitHub опубликован проект API Delta Manifest (ADM) — спецификация небольшого JSON-файла, в котором поставщик API может описывать изменения не только текстом для людей, но и структурированно для скриптов, CI и AI-агентов. Идея проекта: заменить расплывчатые записи в changelog на формат, где явно указано, какой endpoint, поле или SDK затронуты, насколько изменение критично и до какой версии безопасно обновляться.
Что именно предложено
ADM v1 описывает сам формат манифеста. Поставщик API должен публиковать файл по фиксированному адресу:
https://api.example.com/.well-known/api-delta-manifest.json
Это использует распространённый подход .well-known, знакомый по security.txt и discovery-документам OAuth. Практический смысл — агенту или внутреннему инструменту не нужно знать, где у конкретного провайдера лежит changelog: можно проверить один предсказуемый путь.
В примере из репозитория манифест содержит adm_version, provider, generated_at, latest_snapshot и массив entries. Каждая запись включает id, дату релиза, severity, kind, заголовок, описание и поверхность изменения: endpoints, fields, sdk_packages с экосистемой, именем пакета и минимальной безопасной версией.
Как это должно работать
Сценарий, на который нацелен ADM, выглядит так: провайдер меняет поле API, например переименовывает charges.source в charges.payment_method. Вместо того чтобы прятать это в абзаце релиз-нота, он публикует запись с типом изменения field_rename, severity: breaking, списком затронутых endpoint’ов и SDK.
Такой файл уже можно обработать программно: отфильтровать breaking changes, сопоставить endpoint’ы с кодовой базой, проверить зависимости, создать задачу или подсказать AI-агенту, где искать устаревшее поле. В контексте инструментов вроде Claude Code, Cursor, Devin или Copilot workspace agents это особенно заметно: агентам часто поручают читать проект и предлагать PR, но исходные changelog’и обычно написаны так, что требуют человеческой интерпретации.
Почему это важно
Подтверждённая часть проекта — это именно спецификация формата ADM v1, а не готовая экосистема. Тем не менее направление важное: интеграции всё чаще ломаются не из-за отсутствия changelog, а из-за того, что changelog невозможно надёжно разобрать машиной. Для команд, зависящих от платежных, коммуникационных, облачных и прочих внешних API, структурированный сигнал о breaking changes может быть полезнее длинной страницы релиз-нотов.
Авторская интерпретация: ADM пытается сделать для изменений API то, что OpenAPI сделал для описания текущего состояния API. OpenAPI отвечает на вопрос «как сейчас устроен интерфейс», а ADM — «что изменилось и насколько это опасно для потребителя». Если такой подход приживётся, агенты смогут работать с обновлениями API менее эвристически.
Ограничения v1
В репозитории явно указано, что v1 намеренно ограничен манифестом. Доставка codemod’ов, webhooks и клиентские инструменты названы естественными следующими шагами, но не входят в текущий объём. Поэтому пока ADM не решает всю цепочку миграции: он не исправляет код сам по себе, не гарантирует корректность записей и не отменяет необходимость тестов.
Главное ограничение — принятие провайдерами. Формат полезен только если API-платформы будут регулярно и аккуратно публиковать такие файлы. Также из доступного описания нельзя делать выводы о зрелости стандарта, безопасности механизма публикации или поддержке крупными вендорами: это пока проект спецификации на GitHub, а не общепринятая практика.
Источники