Проектирование API *

На стенде ИИ-агенту легко быть умным: идеальный контекст уже собран, а реальные базы данных остались за кадром. Но в проде ему придется самому ходить в CRM, банковское легаси и внутренние сервисы, получая реальные права доступа.

Здесь кроется главное противоречие внедрения LLM. Без доступов агент бесполезен, а с ними — превращается в потенциально опасного инсайдера. Любая ошибка в чате может обернуться реальным запросом к системе от имени служебного аккаунта, и ограничения в промпте вроде «не брать чужое» здесь не помогут.

Именно этот разрыв между красивым демо и суровой энтерпрайз-реальностью стал темой дискуссии на канале Ai4Dev.

Разбираем технические замечания к старой версии Telegram-бота: что действительно требовало исправления, как устроен текущий продукт и чем публичные анкеты отличаются от приватных данных.

Показываю, как собрать пилот универсального шеринга вещей без собственного производства и приложения за 20 миллионов: готовый шкаф, доставка, заводской софт, API и собственный web-слой. Внутри - реальные цены, архитектура и бюджет одной точки до 250 тысяч рублей.

Синяя галочка есть. Ответа нет. Мой собственный бот в MAX игнорирует моё же сообщение: сервер отвечает 200 OK, в логах чисто, а человек на другом конце ничего не видит. Так начались четыре вечера отладки Bot API нового российского мессенджера — четыре грабли, которых нет в документации. Где живёт токен. Почему 404 на чат, в котором ты прямо сейчас переписываешься. Как молча испаряется webhook-подписка. И почему MAX не говорит, которому из твоих ботов написали. Собрал всё, чтобы следующему хватило получаса вместо недели.

Для крупной федеральной компании из телеком-сектора наша команда разработала закрытую семейную платформу для сотрудников и их детей. Один родительский аккаунт объединяет несколько детских профилей, а внутри находятся тематические районы, викторины, мини-игры, творческие задания, личный прогресс, баллы и общий рейтинг.

Название заказчика и самой платформы я не раскрываю по NDA. Для этого разбора важнее масштаб задачи: речь идёт не об эксперименте с генерацией картинок, а о production-продукте, где AI-механика должна работать вместе с авторизацией, детскими профилями, расписанием контента, очередями, файловым хранилищем и правилами начисления баллов.

Одной из творческих активностей стала «виртуальная роспись» городского здания. Пользователь выбирал фотографию фасада, загружал собственный рисунок, а система превращала его в изображение на стенах. Здание должно было остаться узнаваемым, а рисунок - стать частью реальной архитектуры, а не потеряться в новой генерации.

На уровне интерфейса всё выглядит просто: выбрать основу, загрузить рисунок, дождаться результата. На уровне production-системы задача быстро перестаёт быть «вызовом AI API». Прямого доступа к OpenAI API с российского сервера нет. Сама операция длительная, работает с приватными файлами и может завершиться сетевой ошибкой, ограничением провайдера или отказом модерации.

Ниже - технический разбор этого конкретного потока: от React и очереди Laravel до небольшого собственного proxy-сервиса, встроенного в архитектуру основной платформы.

За полгода написал ряд интеграций с Битрикс24 в разных архитектурах: приложение для Маркета (PHP, 6 порталов), клиентский расчётный сервис (Node.js + PostgreSQL) и cron-синхронизатор legacy-CRM без UI и без OAuth вообще. Мультитенант везде решён по-разному, и это не случайность, ведь каждая архитектура точно закрывает свою нишу.

Внутри: сравнение трёх способов хранить OAuth-токены под 6+ порталов, разбор пяти неочевидных деталей REST API (oauth.bitrix24.tech-обход, POST vs GET на рефреше, rate limit 2 req/sec, batch на 50, буфер 5 мин), куски кода на PHP и TypeScript.

Отдельная часть — лицензирование через материнский смарт-процесс. У продукта, распределённого по клиентским порталам, нет своего backend’а, поэтому control-plane я вынес на служебный портал агентства: смарт-процесс «Лицензии», бизнес-процесс на изменение счётчика запросов, webhook approve/decline с secret. Такого паттерна в документации Битрикс24 нет — а он работает уже несколько месяцев и не требует ничего сверх штатной функциональности платформы.

Матрица «что выбирать под задачу» в конце.

В какой-то момент у нас, как и у многих команд, появился соблазн проверить: а можно ли уже не просто просить AI «написать user story», а действительно встроить его в рабочий процесс аналитика? Например, дать агенту вводные по задаче, макеты в Figma, примеры документации и требования к оформлению, и получить на выходе нормальный Use Case, API-спецификацию, PlantUML-диаграмму и аккуратную страницу в Confluence.

Звучит красиво. 

Особенно если вы когда-нибудь вручную переносили сценарии из заметок в Confluence, сверяли шаги с макетами, оформляли вкладки с HTTP-запросами, проверяли коды ошибок и пытались не забыть все вопросы, которые «надо потом уточнить».

В статье расскажу, насколько мы близки к этой утопии — как протестировали работу ИИ в реальном аналитическом процессе в нескольких кейсах: для подготовки Use Case, аналитических артефактов, публикации в Confluence и в работе с Figma.

Сегодня разберём, как ИИ в CRM прошёл путь от расшифровки звонков до выполнения действий.

В конце соберём собственное приложение, которое объединяет эти возможности на платформе для вайбкодинга от Битрикс24.

Привет, Хаброжители! При разработке современных систем, таких как веб-приложения, микросервисы и IoT- устройства, программный интерфейс (API) необходим для обмена данными. Авторы Лукаш Дыновски и Марцин Дулак делятся с разработчиками и архитекторами ПО опытом проектирования и реализации ключевых типов API: REST, GraphQL, gRPC, веб-хуков, WebSocket и других.

В книге подробно рассматриваются наиболее популярные стили API с точки зрения сетевой модели, архитектурных паттернов и системных требований. Вы научитесь выбирать оптимальные варианты для своих приложений, оценивать компромиссы и применять практические рекомендации по реализации и интеграции API в реальных системах.

Чтобы AI-агент понимал инженера, индустрия предлагает поставить между ними еще одну большую языковую модель. Мы поставили модель на 34 млн параметров, в несколько десятков раз меньше, и она справляется лучше.

Секрет в данных. 200 тысяч пар «формулировка задачи → элемент КОМПАС API», где негативные примеры подбирались специально коварные: одноименные методы разных интерфейсов, соседние get/set одного свойства, кандидаты, которых базовая модель ошибочно ставила на первое место. Дообучение заняло меньше пяти часов на одной видеокарте, а Hit@5 на запросах, где метод описан задачей, а не именем, вырос с 5,8% до 79,6%.

Но поиск это только вход. Дальше каждый кандидат проходит через граф типов, константы берутся из настоящих DLL, код сверяет компилятор, а недокументированное поведение агент выясняет экспериментами в живом CAD: пишет зонд, запускает в песочнице, читает результат. Выдать догадку за факт ему негде, на каждом шаге его встречает проверка.

В статье реальные логи, метрики трех бенчмарков, включая неудобные для нас, и объяснение, почему в продакшен пошла именно первая версия модели, а не две следующие.

В статье рассматривается реализация типобезопасного HTTP runtime поверх QNetworkAccessManager и современного C++20. Разберём использование сoncepts для проверки контрактов Request/Response на этапе компиляции, поддержку QFuture и callback API, реализацию retry-политик с exponential backoff, выделенный поток обработки сетевых запросов, а также механизмы управления жизненным циклом задач и graceful shutdown.

Управление API, или API management, за два года превратилось из узкой инженерной темы в самостоятельное направление корпоративного ПО. После ухода зарубежных платформ многие компании остались с сотнями интеграций и без единого инструмента, который ими управляет. То, что раньше держалось на лицензии одного вендора и нескольких архитекторах, рассыпалось на множество разрозненных подключений.

К июню 2026 года в России доступно несколько зрелых отечественных решений. В этом обзоре разберём три, по которым чаще всего идёт сравнение: NEOMSA APIM от компании Neoflex, Platform V Synapse API Mesh от СберТех и MWS Octapi от МТС Web Services. Все три входят в реестр российского ПО, но задачу управления API закрывают по разному, и понимание этих различий важнее, чем сравнение отдельных функций.

Материал написан как разбор для архитекторов и технических руководителей. Мы опираемся на публичные данные вендоров, отраслевую аналитику и опрос компаний, отмечаем сильные стороны каждого решения и сценарии, в которых оно раскрывается лучше всего. 

Выбор здесь про то, какая задача у вас основная: отдельное управление API или интеграция в целом. Под три типичных сценария удобно держать в голове три ориентира.

Недавно я вёл урок по прототипированию сервисов в Cursor. На рабочую часть ушло максимум 40 минут: 15–20 минут я рассказывал, 20–25 минут мы работали. Из этого времени сам Cursor чистыми отработал минут десять, остальное я говорил, копировал промпты и показывал на экране. На выходе получился репозиторий с прототипом редакционного конвейера для новостного сайта: оркестратор на 10 шагов, 10 ролей‑субагентов, 8 файлов правил, канон артефактов прогона. И тут же, при зале, мы прогнали цепочку целиком: от сырых источников до готового черновика новости и вердикта авто‑судьи. Прикладного кода: ноль строк. Каталога src/ в проекте нет вообще.

Сразу сниму ожидание магии. Мы не собирали работающий сервис: ни бэкенда, ни планировщика, ни деплоя. Прогон исполнили агенты Cursor по правилам, а не какая‑то запущенная система. Целью было показать практику: алгоритм будущей системы можно целиком проработать на уровне правил, до того как написана первая строка кода.

Теневые API редко появляются из злого умысла. Чаще это побочный эффект быстрой разработки: временный маршрут для пилота, отдельная точка доступа для мобильного приложения, старая версия, которую забыли отключить, или внутренний сервис, внезапно опубликованный наружу. В статье разберём, почему официальные реестры API расходятся с реальностью, откуда берутся Shadow API и как начать их искать без многомесячного проекта.

Привет, Хаброжители! Улучшаем скорость и качество с APIOps и OpenAPI.

Создавайте качественные, согласованные API и быстро выпускайте их на рынок благодаря автоматизации разработки! Эта книга научит инновационному подходу – как применять рабочие принципы непрерывной доставки (CD) и DevOps на всем протяжении жизненного цикла API. Преобразуйте набор отдельных задач в бесшовный управляемый пайплайн с поддержкой автоматизированного тестирования, итеративных улучшений и надежной документации.

Есть два способа узнать, что вам пришло письмо. Первый — каждые тридцать секунд бегать к почтовому ящику и заглядывать внутрь. Второй — почтальон звонит в дверь, когда письмо реально есть.

Long Polling — это первый способ. Бот в бесконечном цикле долбит getUpdates на серверы Telegram: «есть что‑нибудь? а сейчас? а сейчас?». Telegram, надо отдать ему должное, держит соединение открытым и отвечает не мгновенно, а когда появляются апдейты — поэтому polling и называется long. Но суть не меняется: инициатор — вы, соединение висит постоянно, и весь этот механизм живёт внутри одного вашего процесса.

Webhook — это почтальон. Вы один раз говорите Telegram: «вот мой HTTPS‑адрес, стучись сюда». Дальше при каждом новом сообщении Telegram сам делает POST‑запрос на ваш эндпоинт с JSON‑апдейтом внутри. Нет сообщений — нет запросов. Нет запросов — нет расхода ресурсов.

Для пет‑проекта на пять пользователей разницы никакой, поллинг даже удобнее — не нужен домен и сертификат. Но как только бот становится частью нагруженной системы, вебхуки выигрывают по всем фронтам: апдейт прилетает мгновенно, а не в конце очередного цикла опроса; входящий трафик — это обычные HTTP‑запросы, которые можно балансировать между несколькими инстансами; и главное — бот превращается в обычный веб‑сервис, к которому применим весь стандартный инструментарий: Nginx, healthcheck'и, метрики, горизонтальное масштабирование.

По данным GitGuardian (State of Secrets Sprawl), только за 2024 год в публичный GitHub утекло около 23,7 млн секретов — ключей API, токенов, паролей. Подавляющее большинство — не результат взлома, а обычные коммиты, логи и клиентские бандлы. Свежий ключ, попавший в публичный репозиторий, боты начинают пробовать меньше чем через минуту.

Вывод, к которому мы пришли после N-го инцидента: бороться за то, чтобы ключ не утёк — проигранная война. Выигрышная — сделать утечку бесполезной.

Я давно хотел убрать из backend‑разработки одну особенно липкую рутину: когда для каждой новой сущности снова и снова приходится собирать одни и те же слои REST API — repository, service, handlers, request/response модели, OpenAPI, auth, тесты, curl‑примеры, Docker и прочую инфраструктуру.

В этой статье рассказываю про query‑first подход и open‑source Go CLI rest, который позволяет реализовать эту идею. Смысл простой: если SQL‑запросы или MongoDB‑контракты уже описывают, какие операции нужны приложению, то из них можно сгенерировать согласованный каркас REST‑сервиса.

В статье показано, как это работает для PostgreSQL и MongoDB, что именно генерируется, что такоеrest doctor и почему цель инструмента — не заменить бизнес‑логику, а снять первые 80–90% повторяющейся ручной работы.

Обычно процесс разработки API выглядит так: мы пишем контроллер. Затем каким-то образом его документируем. После чего фронтер, опираясь на такую документацию, пишет клиент.

Мы делаем одну и ту же работу трижды.

В прошлой статье я рассказывал, как избавиться от первого дублирования. С помощью бандла sunrise-studio/symfony-openapi можно генерировать OpenAPI-документ из кода, минуя процесс документирования.

Но это решает проблему только наполовину. Если OpenAPI-документ вытекает из кода, то клиент должен вытекать из OpenAPI-документа. Иначе написание клиента – и есть то самое дублирование.

В этой статье я расскажу как замкнуть цепочку:
Controller → OpenAPI → Client → Feature
Где каждый последующий шаг вытекает из предыдущего, а не дублирует его. 

Я хотел использовать Claude прямо в мессенджере MAX — без браузера, без переключения контекста. Готового решения не было. Нашёл на GitHub китайский проект cc-connect — Go-фреймворк с plugin-архитектурой для подключения AI-агентов к мессенджерам. Telegram, Feishu, Discord там были. MAX — нет.

Написал адаптер, открыл PR. Приняли. Теперь поддержка MAX — часть основного репозитория.

Что такое cc-connect

cc-connect — Go-фреймворк с чёткой трёхслойной архитектурой: