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

Эксперимент на примере классификации изображений CIFAR-10 с использованием фреймворка ICO: параллельная загрузка данных, аугментации, тренировка и валидация.

Почему без интеграции ИТ‑систем все усилия по цифровизации умножаются на ноль.

В статье разберём четыре подхода, которые компании выбирают, когда доходит до интеграций ИТ‑систем: классические «точка‑точка» (они же «спагетти‑код»), брокеры сообщений вроде Kafka и RabbitMQ, Open Source‑решения и готовые ESB‑платформы. Посмотрим на примерах, как каждый из них работает в бою, какие грабли ждут на каждом пути, и почему «бесплатно» на входе часто оборачивается очень дорогим сопровождением.

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

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

Работа с файлами в REST API Битрикс24 — та задача, где документация заканчивается ровно там, где начинаются проблемы. Официальные примеры показывают, как загрузить один файл в одно поле. А дальше выясняется, что у crm.item.update и crm.deal.update разные несовместимые форматы, что вложенный base64 через http_build_query уходит в никуда, а сервер при этом честно отвечает «result».

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

Собрал всё в один разбор — шесть подходов с кодом и восемь граблей:

два формата файлового значения, которые нельзя смешивать, и почему при смешении затираются уже прикреплённые файлы;

тихий провал: HTTP 200, в ответе result, поле не обновилось;

useOriginalUfNames=Y, без которого UF_CRM_* молча игнорируются;

downloadUrl приходит с пустым auth= и без подстановки токена не скачивается, а при протухшем токене вместо файла отдаётся HTML-страница с кодом 200;

у одного изображения бывает несколько URL, и часть из них не работает — пришлось делать скоринг вариантов по эвристике.

В конце — таблица «что брать под какую задачу» и чеклист граблей. Двадцать блоков кода, всё из боевых проектов.

Каждый день мы натыкаемся на одни и те же грабли в связке фронта и бэка. Каждые такие грабли — это деньги и время. А если ещё и договариваться не умеем, процессов нет и решать никто не берётся, то дальше начинаются конфликты, атмосфера в команде проседает и проблемы копятся ещё быстрее.

Статья не про саму автогенерацию — с ней всё понятно, про неё и без меня написано достаточно. Мы внедрили генерацию типов из OpenAPI, и она вытащила наружу то, что с генерацией напрямую не связано: кто не хочет писать комментарии, почему у одной сущности два имени и почему у нас падал dev. По сути — про команду, эго и умение договариваться.

Сразу оговорюсь: это не единственно верный путь. Команды и компании разные, у всех свои нюансы, я рассказываю, как было у нас. Но если автогенерации у вас ещё нет и вы соберётесь её внедрять — будете хотя бы знать, что вас ждёт.

Telegram показал Rich Messages с интерактивными кнопками на примере шахмат. Я захотел проверить подход на более насыщенном сценарии и собрал покер‑бота.

Разбираю, как хранить состояние, обновлять одно сообщение, обрабатывать callback и защищаться от устаревших действий.

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

Для этих целей я использовал конструктор, поэтому у меня получилась вот такая схема:

Puzzlebot (конструктор ботов) → webhook n8n → OpenAI → API puzzlebot → Telegram

Т.е puzzlebot отвечает за сценарий и общение с пользователем. n8n принимает данные, вызывает модель и возвращает результат. ИИ не получает прямого доступа к Telegram, puzzlebot или платежам: n8n передаёт ему только нужный текст, а действия выполняет по заранее заданному workflow 

Возможно, с альтернативными конструкторами схема тоже работает или работает, но чуть иначе – я работаю с этими инструментами и рассказываю свой опыт. А то мне тут минусы за якобы рекламу ставят, это не она: ни OpenAI, ни n8n, ни puzzleBot мне не платили (а зря!))))

Мы устали искать Swagger по чатам и написали свой агрегатор.

— Где актуальный контракт сервиса рассрочек?
— В репозитории.
— В каком?
— Сейчас найду ссылку.

У нас этот диалог повторялся регулярно. Формально API-документация была. Фактически — реестр хранился в памяти нескольких сотрудников, а поиск работал через WB Wiki и корпоративный мессенджер Band.

Меня зовут Олег Леонов, я руковожу отделом системного анализа в финтехе RWB. Мы занимаемся рассрочками и кредитами, инвесткопилкой и WB Кошельком в мобильном приложении и на сайте.

Swagger Aggregator я начинал как пет-проект. Хотел собрать контракты в одном месте и искать по ним примерно так же, как по коду. Потом агрегатор прижился у команды. Расскажу, что в итоге получилось и на каких местах я потратил больше времени, чем рассчитывал.

Если бот копирует один и тот же пост в десять каналов, в Google Analytics все клики свалятся в одну кучу. URL у скрытой ссылки живёт не в тексте, а в MessageEntity, а copyMessages копирует его как есть. Ниже — как пересобрать пост под каждую площадку, не сломав жирный шрифт, эмодзи и health‑check.

Telegram умеет одно очень удобное действие: copyMessages. Берёте сообщение из чата A, кладёте в чат B — форматирование, медиа, альбом, скрытые ссылки, всё на месте. Для рассылок и зеркал это идеальный метод.

Для рекламы он ломает самое важное.

Рекламодатель покупает размещения в разных каналах и смотрит в свою аналитику: откуда пришёл клик. Если во всех десяти постах в text_link лежит один и тот же https://shop.example/sale, UTM бесполезен. Каналы неразличимы. Сделка неразличима. Дата размещения неразличима.

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

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

В этой статье разберу более устойчивый вариант: отдельный API‑слой между мобильным приложением и существующей системой. Без полной переработки монолита и без попытки сразу перейти на микросервисы.

Корпоративные команды используют MCP-шлюзы, чтобы контролировать, как ИИ-агенты получают доступ к инструментам, сервисам и корпоративным данным. Agentgateway, проект с открытым исходным кодом, развиваемый под эгидой Agentic AI Foundation, маршрутизирует MCP-, Agent-to-Agent-, LLM- и API-трафик между клиентами и внутренними сервисами. Его открытый код, тесты и рекомендации по безопасности делают его полезным объектом для практического изучения безопасности корпоративных шлюзов.

Почему мы классифицируем движение руки, а не картинки со светофорами — и как встроить это в форму двумя строками

Картиночные капчи в 2026-м решаются моделями компьютерного зрения за миллисекунды, а каждый ваш клик по «выберите автобусы» бесплатно размечает чужой датасет. Плюс две свежие проблемы: Google в начале 2025 срезал бесплатный лимит reCAPTCHA с 1 000 000 до 10 000 проверок в месяц, а с апреля 2026 ужесточил модель ответственности за данные по GDPR. Из России reCAPTCHA к тому же нестабильна.

Общая проблема для сети — как доказать, что ты человек, не сдавая паспорт, лицо и номер телефона. Мы предлагаем: drop-in капчу, которую посетитель не кликает, а рисует. В описании — архитектура, ML-часть, приватность и код интеграции. Проект открытый. Буду рад аргументированным замечаниям.

Я измеряю видимость компаний в поиске и в ответах нейросетей. Свой сайт проверил последним: клиентские проекты всегда впереди своих. Результат отрезвляющий — все страниц есть в поиске, проблем с индексацией нет, а в вопросах про услугу без упоминания названия ноль появлений из тридцати двух возможных.

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

Задача звучит просто: выяснить, называют ли бренд ChatGPT, Claude, Perplexity, Gemini, Алиса AI и GigaChat, когда пользователь спрашивает совета или ответа у ИИ. На практике эта задача раскладывается на десятки технических решений, каждое из которых меняет результат в разы. Ниже устройство замера, формат хранения и три моих ошибки, которые обесценивают всю работу.

Цифру «+1100%» я увидел в чужом пересказе, и это ровно тот жанр новости, после которого приходят спрашивать, что будет со сметой. Часть нашей нагрузки на DeepSeek пакетная, ее можно двигать по времени суток, так что вопрос был прикладной: насколько сильно двигать и куда.

Я открыл прайс, взял профиль своей нагрузки, перемножил. Получилось 2,3. Перепроверил на других профилях, получилось от 2,3 до 2,9. Роста в 11 раз не вышло нигде.

Дальше выяснилось, что 12,1 существует, живет ровно в одной клетке прайса из шести и весит в счете меньше 10%. А по дороге я наткнулся на вещь поинтереснее: пиковые окна DeepSeek объявил в UTC, и в московском времени они ложатся так, что из рабочего дня дорогим оказывается ровно промежуток с 10:00 до 13:00, после чего до 04:00 следующих суток все идет по дешевому тарифу.

Ниже разбор прайса, реверс-инжиниринг пиковых окон, таблица «найдите свой часовой пояс», калькулятор на 40 строк и фрагмент crontab, который сдвигает батч за 13:05.

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

Через несколько дней (говно)кода стало много — вменяемого сервиса не получилось.

Один BFS принимал map[string][]string. DFS жил на другом типе графа. В одной реализации направленность задавалась на уровне графа, в другой вытекала из того, как было записано ребро. Опции существовали, но их комбинации не образовывали понятной политики. Result types возвращали срезы и числа, однако я не мог внятно ответить, что именно они гарантируют.

Проблема была не в том, что LLM «не умеет BFS». Я попросил реализации раньше, чем сформулировал общий контракт данных. Генератор заполнил пустые места правдоподобными допущениями — которые, очевидно, не совпали в разных кусках кода.

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

В начале августа я сел делать игру для мессенджера MAX – обычный вордли, слово из пяти букв, шесть попыток. Мини-приложение на ванильном JS, сервер на Go, самый дешёвый VPS. По моим прикидкам – три вечера.

Первый вечер целиком ушёл на то, чтобы сервер вообще смог поговорить с API мессенджера. Не на игру, не на словарь – на TCP-соединение.

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

Собрал шесть AI-сервисов, которыми сейчас можно пользоваться бесплатно или с крупными стартовыми кредитами: FLUX 3 для генерации видео, Manus, Postman Agent Mode, Claude через API, Atomesus и Deepgram с $200 на Voice AI. Проверил регистрацию и условия на своих аккаунтах, добавил скриншоты и короткие инструкции. Актуально на 12 августа 2026 года.

Держите открытыми две вкладки. В одной — интернет-банк, куда вы залогинены и где на экране висит ваш баланс. В другой — какой-то сайт, на который вы забрели по ссылке из выдачи, ничего особенного. Теперь вопрос, который на первый взгляд кажется надуманным, а на деле упирается в фундамент всей веб-безопасности: что мешает скрипту со второго сайта взять и прочитать ваш баланс из первого?

Encore зародился как фреймворк на Go, и на Go там были написаны среда выполнения, интерфейс командной строки (CLI), парсер и компилятор. Когда мы решили поддерживать TypeScript, логичнее всего было бы написать на TypeScript и среду выполнения тоже, либо достроить к среде выполнения Go какой‑нибудь мостик. Но в итоге пришли к тому, что написали новую среду выполнения с нуля на Rust.

Привет, Хабр! Я Матвей Лихота, старший Go-разработчик. В предыдущем материале я показывал, как получить Go-код из OpenAPI. Теперь хочу сделать еще один шаг назад — к моменту, когда контракта еще нет.

На демо частенько можно увидеть, как по простому запросу «напиши CRM» или «собери интернет-магазин» LLM уже через минуту готовит сервер, модели, миграции и тесты. Но в реальности, конечно, все происходит чуть иначе: проверяем код, а там — сюрприз-сюрприз ошибки. Повторив тот же промпт, мы получим другую архитектуру и снова потратим время на проверку. И нет гарантии, что после переделки ошибок не станет еще больше.

Конечно, все дело в промпте. Согласитесь, странно просить модель понять задачу, выбрать архитектуру, определить границы и все реализовать за один шаг? Что, если LLM сначала проектирует систему и выпустит OpenAPI, Proto, JSON Schema, CloudEvents и AsyncAPI? А код мы добавим чуть позже: за повторяемую часть будут отвечать обычные генераторы, а за проектно-зависимую — разработчики и агент в контексте репозитория.

Такой подход, где главным артефактом становится контракт, а код — его производной, можно назвать Documentation Driven Agent Development или Specification Driven Agent Development. Как он работает — покажу на примере разработки простой автоматической телефонной станции (АТС), а еще проведу границу между генераторами и агентами.