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

В какой-то момент у нас, как и у многих команд, появился соблазн проверить: а можно ли уже не просто просить 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-фреймворк с чёткой трёхслойной архитектурой:

В июне 2026 года опубликован RFC 10008 — «The HTTP QUERY Method». Он добавил в HTTP новый стандартизованный метод QUERY, который также появился в реестре HTTP‑методов IANA: запрос с телом к конкретному адресу, который по смыслу остаётся чтением и не должен менять данные на сервере.

Метод нужен для давно знакомого случая: нужно передать сложные параметры поиска, фильтрации или отчёта, а по семантике это всё ещё безопасная операция чтения.

Обычный GET для таких запросов часто неудобен: параметры быстро превращаются в длинный URI или в собственный мини‑язык фильтрации внутри строки запроса. POST удобнее для передачи структуры, но передаёт не тот сигнал промежуточной инфраструктуре.

Приглашаю посмотреть, что там в RFC напридумывали, и чем нам это грозит — и чем поможет!

«Нам нужно сделать регрессионное, функциональное и интеграционное тестирование» — а ты автоматизатор и уже задумываешься о том, что попал куда‑то не туда. Или новичок решает пойти в тестировщики, смотрит вакансии и видит, что этих видов тестирования чуть ли не сотня. Как же понять, что от тебя требуют и куда идти? Попробуем разобраться.

Обычный LLM-агент, которого просят писать Python-скрипты под КОМПАС-3D, ошибается системно: придумывает несуществующие методы, путает две ветки COM API, ссылается на отменённые ГОСТы, подставляет невалидные значения в аргументы. Промпты и примеры это не лечат. В статье разбираю другой подход: контекст-слой из нескольких механизмов, где каждый класс ошибок ловится отдельно ещё до того, как код дойдёт до живого CAD. Внутри граф API на 47 тысяч узлов, справочник валидных значений, база действующих и отменённых стандартов, проверка сгенерированного кода настоящим C#-компилятором и разбор ошибок исполнения на живом КОМПАС-3D. С примерами кода и реальным фидбеком, который получает агент. Заодно объясняю, почему для такой задачи отказался от MCP.

Один User сначала кажется удобным: его можно принять в запросе, вернуть из API, сохранить в базу и передать дальше.
Но со временем такой класс смешивает разные границы и перестаёт защищать код.

Разбираю на Python-примерах, чем отличаются DTO, schema, model и entity — и когда отдельные классы действительно нужны.

Тестируем платформу Битрикс24 Вайбкод для создания полезных приложений в своём бизнес-портале с помощью ИИ-агентов.

Сегодня сделаем паспорт клиента: собираем в одном месте всё, что нужно знать о компаниях в нашем бизнес-портале: контакты, сделки, лиды и любые активности. Рассказываем по шагам свой опыт работы с платформой — что было просто, как строили работу, где ИИ ошибался и пришлось ли что-то исправлять вручную.

В этой статье - мой рабочий шаблон для описания REST API в ТЗ для разработчиков. В качестве примера я спроектировала учебную базу данных для финтех-системы. Она не привязана к реальному проекту и нужна только для того, чтобы показать, как описывать REST API по шаблону.