Привет, на связи Виктор Степанов, лид одной из core-команд ИИ-платформы для работы с кодом GitVerse. Сегодня я хочу поделиться коротким рассказом о том, как мы начали проектировать и разрабатывать публичный API для нашей платформы.
Начнём с того, что в любой более-менее крупной информационной системе есть несколько пользовательских интерфейсов. Например, привычные всем графические интерфейсы или более редкие, но всё же существующие терминальные. Но все они не могут обойтись без самого главного, того, что связывает весь софт воедино — программного интерфейса. Который, в свою очередь, может быть внутренним или публичным.
Проектирование публичного интерфейса, с которым впоследствии будут иметь дело наши пользователи, — занятие, требующее от разработчика, с одной стороны, максимально кропотливого подхода и внимания к деталям, а с другой — скорости, так как пользователи ждут результата как можно скорее.
REST или не REST?
Одним из главных вопросов, вставших перед нами, стал выбор типа API. Какого рода публичный API мы хотим предложить нашим пользователям? Это будет REST, GraphQL или что-то другое? С учётом того, что REST является своего рода мейнстримом в клиент-серверном взаимодействии, мы остановились именно на нём.
Но сначала давайте проговорим, что такое REST (REpresentation State Transfer) и что нам нужно сделать, чтобы наш API считался RESTfull. С практической точки зрения, чтобы интерфейс считался таковым, он должен соответствовать следующим требованиям:
Обеспечено моделирование взаимодействия между производителем и потребителем, при котором производитель моделирует ресурсы, доступные потребителю для взаимодействия.
Запросы от производителя к потребителю выполняются без сохранения состояния — то есть, производитель не кеширует информацию о предыдущем запросе. И чтобы выстроить цепочку запросов к тому или иному ресурсу, потребитель должен отправить производителю для обработки всю необходимую информацию.
Запросы кешируются, поэтому производитель может предоставлять потребителю подсказки, где это уместно. В НТТР это часто обеспечивается информацией из заголовка.
Потребителю передаётся единый интерфейс.
Система многоуровневая и абстрагируется от сложности систем, находящихся за REST-интерфейсом.
Кроме учёта этих требований нам нужно было решить, какому уровню зрелости API мы хотим соответствовать. Тут стоит напомнить, какие уровни зрелости существуют и что это вообще такое. В далёком уже 2008 году Леонард Ричардсон вывел эвристическое правило о зрелости API на основании изучения множества REST API:
0 уровень, нет REST: API использует один URL и HTTP (обычно POST) для всех операций. Похоже на RPC или SOAP.
1 уровень: введены отдельные URL для ресурсов, но часто используется только GET и POST.
2 уровень, HTTP-глаголы (методы): используются правильные HTTP-методы: GET, POST, PUT, DELETE и другие для соответствующих операций.
3 уровень, HATEOAS (Hypermedia as the Engine of Application State): API возвращает ссылки на доступные в цепочке запросов действия. Клиент «путешествует» по API динамически.
Начиная работу, мы понимали, что не должны опускаться ниже третьего уровня, чтобы получить более-менее внятный интерфейс, с которым конечному потребителю будет удобно общаться. Но надо ли нам замахиваться на третий уровень, ведь он требует массивного проектирования наших интерфейсов, а выпустить функциональность хочется как можно скорее.
С практической точки зрения третий уровень избыточен, и хотя навигация внутри API остаётся большим преимуществом HATEOAS, его проектирование и дальнейшее использование было бы достаточно хлопотным занятием. А отсутствие полной спецификации возможных взаимодействий на момент создания нашего API заранее сделало бы эту работу чрезмерно запутанной и трудноприменяемой для конечного пользователя.
Лучшие практики
При проектировании публичного API ещё одним ключевым моментом, требующим внимания, оказалась его совместимость. В мире, где существуют признанные гиганты, под работу с которыми уже заточены сотни утилит и написано немало пользовательского кода, мы оказались перед выбором: выстраивать интерфейс, исходя из структуры своей системы, или делать его максимально похожим на интерфейс GitHub, чтоб нашим пользователям было комфортно перевезти свои готовые инструменты, переориентировав их на GitVerse.
Конечно, это потребовало от нас большего количества ресурсов, но взамен мы обеспечили пользователям безболезненную миграцию на наш стек без изменения кодовой базы уже готовых инструментов. В свою очередь ответ на этот вопрос помог нам с ответом на предыдущий. В своём API GitHub использует сокращённую версию HATEOAS, на которую и мы устремили свой взгляд при проектировании системы.
Сообщество приходит на помощь
Теперь пара слов про последовательность создания методов. Какие из них будут важны пользователю в первую очередь? Может быть, это управление репозиториями? Работа с pull request'ами? Очень сложно найти ответ на этот вопрос, когда, повторюсь, под боком есть гиганты, которые уже предлагают всё и сразу.
Но благодаря нашим коллегам из Gramax, которые захотели одними из первых интегрировать свою систему с GitVerse, ответ на этот вопрос нашёлся сам. Вместо того, чтобы пытаться охватить всё и сразу, мы сосредоточились на тех интерфейсах, которые были критически важны для интеграции, и это позволило нам ускорить разработку, избежать лишней работы и быстро получить обратную связь от реальных пользователей.
В первую очередь мы реализовали методы по работе с репозиториями: создание и удаление, управление ветками, а также полный цикл работы с pull request'ами. Параллельно мы разработали API для управления пользователями, включая получение профиля, обновление данных, работу с ролями и разрешениями, что особенно важно для систем с распределёнными командами и строгой политикой доступа.
Все эти методы доступны в публичном API и активно используются командой Gramax, что подтверждает их практическую ценность и устойчивость. Сейчас (в августе 2025) API доступен по запросу на платформе, но скоро будет открыт всем. Более подробную информацию — с примерами запросов, описанием параметров и кодами ответов — можно найти в нашей официальной документации, мы регулярно публикуем актуальные обновления по каждому разделу API.
ИИ-документация
Кстати, по поводу документации есть ещё один интересный факт. Чтобы быстрее создавать и поддерживать документацию публичного API, мы активно задействовали собственные ИИ-инструменты из семейства Giga. Они помогли нам автоматизировать генерацию описаний конечных точек, форматов запросов и ответов, а также примеров использования на основе кода и комментариев в нём. В частности, именно с их помощью мы смогли оперативно подготовить и опубликовать разделы документации по ключевым функциям API, тогда как разработка подобной документации в ручном режиме заняла бы колоссальное время.
Наша цель — не просто ускорить процесс документирования, а создать в будущем полностью автоматизированную систему, которая будет обновлять документацию в режиме реального времени при каждом изменении в API. Это позволит нам сохранять информацию всегда актуальной, снижать нагрузку на разработчиков и предоставлять пользователям прозрачный, понятный и всегда свежий контракт взаимодействия с GitVerse.
Напоследок пара слов о планах на ближайшее будущее. В первую очередь это расширение нашего API: мы хотим сделать так, чтобы пользователи могли управлять всей своей инфраструктурой репозиториев, проектами и командами, не заходя в браузер. Уже сейчас можно работать с репозиториями и пользователями, а в ближайшее время мы добавим поддержку CI/CD, вебхуков, уведомлений и других ключевых функций, чтобы строить вокруг GitVerse полноценные автоматизированные сценарии.
Параллельно с расширением функциональности мы активно наращиваем качество наших интерфейсов: повышаем стабильность, безопасность и скорость отклика. Особое внимание уделяем отказоустойчивости и мониторингу, чтобы API оставался доступным даже в пиковые нагрузки.
Мы уже начали проработку системы версионирования, которая позволит нам развивать API без риска сломать существующие интеграции. А с помощью ИИ-инструментов мы постепенно автоматизируем всё, что можно, от генерации документации до тестирования изменений в API.
Следите за нашими релизами, каждый из них приближает GitVerse к тому, чтобы стать по-настоящему открытой и гибкой платформой для разработчиков. Всё самое интересное — уже в процессе.