Как AI помогает проектировать API

Александр открывает выпуск: сегодня очередная статья Google, продолжение той работы про API governance, которую читали в первом выпуске. Он нашёл её, просматривая статьи Google с конца; внутри оказались отсылки на более раннюю работу — по его словам, примерно двадцать третьего года — и на исследование 2016 года, так что серия сложилась у него в сагу о подходе Google к API. У статьи, по его словам, четыре автора из разных университетов и один из Google, а основной автор предыдущей работы и книги несколько лет назад ушёл в Meta и остался только в благодарностях. Дальше Александр советует приём: перед чтением статьи разобрать её на части — абстракт, обзор предыдущих работ и незакрытый gap, методология, результаты, дискуссия, ограничения, заключение. Нет раздела про ограничения — выглядит так, будто подход авторов безальтернативен. Плохую методологию он показывает карикатурой: спросить на конференции только тех, кто дошёл до доклада, а дошли одни архитекторы, и объявить, что уровень знаний отличный.

Разбор начинают с интро. Авторы отмечают: документов про API много, а насколько контракт удобен, гибок и безопасен, прорабатывается редко. В понимании Павла фокус статьи вообще не про governance, а скорее про developer experience и про то, как реализуются сами контракты: эти три вопроса встают именно при проектировании. Часть про AIP, API improvement proposals, приехала из предыдущей статьи, и Александр просит Павла напомнить его тем, кто не смотрел первый выпуск; по словам Павла, это стандарты, лучшие практики и рекомендации к контрактам, а сам AIP — ещё и процесс добавления правил, который Александру чем-то напоминает Python. Согласованные правила кодируются в линтер, который гоняется по спекам и сразу отдаёт обратную связь. Автор предыдущей статьи, вспоминает Александр, настаивал, что важен не REST как таковой, а ресурсно ориентированный API: зафиксируй действия над ресурсами — и его можно построить и поверх.

Павел сразу натягивает это на банк. Контекст ограничивают REST, grpc и GraphQL выносят за скобки; в основе OpenAPI с зафиксированной версией, а сверху корпоративный стандарт, придуманный внутри Т-Банка лет пять назад для всех REST-контрактов: он стандартизирует коды ответов и делает подход к OpenAPI построже. Получается матрёшка: платформа публичных API добавляет свои теги, дополнительные параметры и более строгие требования к ответам и вложенности объектов. Всё обратно совместимо, конечный контракт полностью соответствует OpenAPI, и внешний разработчик открывает его в Swagger Editor как обычную, только более строгую спеку. Разница с Google — в цене изменения правил: корпоративный стандарт меняет коллегия разработчиков, и одну версию, по словам Павла, выпускали год. Стандарт платформы гибкий — ТЗ от системного аналитика, обсуждение с техлидом, — но не масштабируется; сам OpenAPI выпускает версию примерно раз в пять лет.

Фундаментальных исследований, как в Google, компактная команда не проводит, и Павел идёт от самого очевидного. Опросы прямо в документации работают нормально. Глубинным интервью он доверяет меньше: попадёшь не на того и сделаешь неверные выводы — сейчас на платформе публикуется системный аналитик, который делает избыточный контракт со своими паттернами, формально валидный. Дальше метрики: время от идеи до первых вызовов интеграции, изменение контракта существующего метода (оно отличается от создания раз в десять), скорость второго метода у того же разработчика, карты кликов в документации. Отдельно Павел делит разработчиков на «светлых» и «тёмных»: про внутренних известно почти всё — язык, код в git, примерный time to market, — а над потребителями туман войны, и убрать его — одна из главных целей исследований. Последние идеи — про источники данных: open source, где внешние разработчики комментируют выложенные контракты (однажды, ещё до публикации, человек принёс SDK на языке Crystal), in-source, если наружу нельзя, и публичные ивенты: на IT Пикнике через стенд с игрой «напиши контракт с помощью ChatGPT» за день прошло 500 человек.

Методология статьи стоит на трёх китах: контролируемый эксперимент, качественные интервью о том, как спецификации воспринимают потребители, и эксперты, оценивающие результат модели — ей давали продуктовые требования, кажется, соцсеть для детей и родителей, и просили написать спеку. Групп три: со стандартами и линтером, со стандартами, но без линтера и обратной связи, и без всего. Участникам дали около двух часов, запись экрана и 80 долларов. Первая группа выполнила 71% требований против 62–63% у остальных, а среднее число ошибок, которые потом находил линтер, — около 14 против примерно 19. Отдельная история — воронка: опрос в группе по интересам заполнили 234 человека, около 6%; участвовать согласились 2,5% разработчиков; дошло меньше 1% — 34 подопытных из 4000, причём, по памяти Александра, то ли 34, то ли 33. Павел поэтому считает эксперимент неповторимым, а Александр прикидывает: при десяти тысячах инженеров в банке набралось бы человек четыреста и до конца дошли бы трое — мерить нечего.

Больше всего Александру понравилась оценка потребителей: куски контрактов нарезали в сэмплы и показывали парами — какой нравится больше. Группу со стандартами и линтером выбирали заметно чаще, а группы «стандарты без линтера» и «без всего» статистически не отличались: держаться стандартов сложно, а без фидбэка не понять, правильно ли ты ими пользовался. Вариант, сгенерированный моделью, оценивали примерно десять экспертов со средним стажем около двадцати лет, и именно следование стандартам просело сильнее всего. На стенде команда Павла получила похожий инсайт: чистый GPT без дообучения выдаёт валидный, но некачественный YAML, зато годится, чтобы учить джунов с их страхом белого листа. Отсюда мысль Александра: модель оценивали как отдельно стоящую, а стоило бы дообучить внутреннего ассистента, который уже помогает писать код. Павел же называет замер спидраном: time to market метода — 30 дней, из которых на сам YAML уходит один, остальное — выяснение бизнес-требований и возня со средой.