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

Чат-боты в ресторанном бизнесе чаще всего начинают с простой задачи: снять часть нагрузки с менеджеров и отвечать гостям на типовые вопросы. На практике многие такие решения быстро упираются в ограничения. Бот отвечает шаблонно, не понимает свободный текст, не учитывает контекст гостя, не видит актуальные данные ресторана и при нестандартном запросе просит переформулировать вопрос или вручную переключает диалог на сотрудника.

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

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

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

Описанный подход работает независимо от используемого на проекте стека технологий и особенно полезен в гетерогенных системах. Поэтому я стараюсь приводить примеры из разных языков программирования и технологий: Java, Python, TypeScript, REST, GraphQL, protobuf.

Два часа ночи, у разработчика горит релиз, он подключает ваш API — и получает в ответ голое «invalid_request». Что не так, почему, что делать — ни слова. Сорок минут гаданий и злое письмо в поддержку.

Разбираем, как сделать опыт разработчика (DX) человеческим: как переписать ошибки по стандарту RFC 9457, но для живого человека; почему время до первого успешного вызова — главная метрика онбординга; и отчего предсказуемый, «скучный» API — это комплимент. С готовым шаблоном, который можно прикрутить к себе сегодня.

Ресторанная сеть из 10 заведений обратилась с первичным запросом на доработку Telegram Mini App. В процессе стало понятно, что задача шире: компании нужен не отдельный подрядчик под приложение, а внешний продуктово-технический контур, который сможет развивать несколько цифровых продуктов, поддерживать инфраструктуру, закрывать интеграции и сопровождать эксплуатацию.

За 7 месяцев работы были запущены 6 продуктов:

Добрый день, уважаемые читатели Хабра.

В этой статье я хочу рассказать о продукте APItizer, почему появилась потребность в его создании и какой путь привёл от небольшого Python-скрипта к полноценному инструменту для проектирования REST API-контрактов.

Если вам интересно сразу посмотреть на продукт, добро пожаловать в APItizer (прямая ссылка, вдруг домен не работает).

Из трёх мажоров, описанных в предыдущей статье, два не всплыли в тестах. Они всплыли в двух дизайн-ревью, которые тесты провести не могут.

Держать proto-контракты в одном репозитории удобно, но подключать их целиком в каждый сервис — не очень. Разберём, как автоматически генерировать Go-стабы из proto-файлов, версионировать их как отдельные Go-модули и публиковать через GitLab CI/CD. Бонусом — swagger-документация и GitLab Pages.

Ресторанный холдинг с 10 ресторанами использовал первую версию Telegram Mini App как интерфейс, через который гости могли ознакомиться с заведениями сети. На следующем этапе потребовалось усилить IT-направление: увеличить скорость разработки, стабилизировать систему, расширить функциональность и связать приложение с операционными процессами ресторанов.

В результате Telegram Mini App вырос в полноценный цифровой контур, который объединяет бронирования, мероприятия, меню, банкеты, сертификаты, кулинарию, коммуникацию с гостями, аналитику, админ-панель и интеграции с внешними системами.

На текущем этапе система стабильно держит 11 000 MAU, включает более 200 функций, работает с Remarked, IIKO, RocketData, CRM, Telegram API и внутренними API заказчика. В процессе эксплуатации также была отражена атака на серверы заказчика.

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

Когда я начал поднимать PostgreSQL через Docker для своих проектов, всё выглядело просто: описал сервис в docker-compose.yml, запустил контейнер - база доступна.

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

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

Основная задача проекта — заменить разрозненные FAQ, Wiki, документы и чаты единым интерфейсом доступа к корпоративным знаниям. Сотрудник может задать вопрос в свободной форме и получить ответ с учётом своей должности, прав доступа и актуальной версии документа.

Привет, Хабр! Меня зовут Александр, я Java-разработчик в GlowByte. Работаю в практике управления рисками и комплаенс (Risk & Compliance). Хочу поделиться своим опытом и в целом рассказать о том, чем мы здесь занимаемся. А занимаемся мы автоматизацией систем управления рисками – от AML (противодействие легализации доходов) и операционных рисков до коллекшна (взыскание просроченной задолженности) и систем принятия решений.

Моё направление – как раз последнее: системы принятия решений (СПР). Если коротко, мы автоматизируем стратегии, где нужно в реальном времени перерабатывать кучу входных параметров, учитывать множество факторов и выдавать сложные, комплексные решения. Типичные примеры: оценка риска, предстраховые проверки, системы мониторинга, расчет резервов, расчет комиссионных вознаграждений страховым агентам и многое другое.

Чем это интересно? На выходе – не просто «да/нет», а полноценное управляемое бизнес-правило, которое можно быстро менять без переписывания кода.

В этой статье хочу поделиться опытом разработки backend API на Spring Boot-проекте, где нам пришлось много работать с OpenAPI-спецификацией, динамическими запросами и тестированием бизнес-логики.

В течение последних двух лет мы проделали большую работу по изданию неустаревающих книг, связанных с проектированием и развитием API. Как известно, сам вопрос «Что такое API?» довольно многогранен, и в своё время на Хабре развёрнутый ответ на него дала одна из наших топовых авторов Ольга Назина @Molechka — к настоящему моменту её статья собрала почти 1 350 000 просмотров и 1555 закладок. Книги Ольги Назиной не относятся к этой статье напрямую, но, если вы их ещё не читали, рекомендуем посмотреть все четыре. Будем исходить из того, что API — это предоставляемый программой интерфейс‑контракт, в котором заложены правила взаимодействия с ней, в частности, форматы принимаемых и выдаваемых данных. Нашим главным бестселлером в этой области является книга «Проектирование архитектуры API: Как правильно проектировать, развивать и эксплуатировать API» (вышла на русском языке в июне 2024 года), написанная великим Джеймсом Гофом в соавторстве с Дэниэлом Брайантом и Мэтью Оберном, а также ещё три крутые книги:

— «API как искусство: разработка, поддержка, интеграция» Сергея Константинова (вышла в мае 2024 года)
— «Архитектура бэкенда. API для надежных корпоративных приложений» Владислава Светлакова (вышла в августе 2025 года)
— «Web API. Сборник рецептов: Повысьте уровень JavaScript‑приложений» Джо Аттарди (вышла в сентябре 2025 года).

На этой в продаже появилась следующая книга, наполняющая эту нишу: «Прикладные API для искусственного интеллекта и Data Science» Райана Дэя — оригинал вышел в издательстве «O'Reilly“ в апреле 2025 года. Эта весьма оригинальная книга исследует работу с библиотеками Python и в качестве сквозного проекта рассматривает фэнтези‑футбол. Для нас это первый опыт издания книги с серьёзным включением FastAPI, но в перспективе мы не теряем надежд издать и исходно русскоязычную книгу об этом фреймворке.

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

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

Основная причина — отсутствие единого слоя знаний.

В проекте для ресторанной группы с 10+ заведениями и историей более 15 лет мы сознательно начали не с агентов и не с интерфейсов, а с построения корпоративной RAG-инфраструктуры. Этот слой стал основой всей последующей AI-архитектуры.

Знакомая работает в IT-департаменте организации с 16 филиалами и ~5000 единиц оргтехники на балансе. Попросила: “Сделай сервис, чтобы загрузить фотку шильдика, и он сказал, у кого эта железка стоит”. Звучит просто. На практике это вылилось в production-сервис с распознаванием по фото через Claude vision, ETL из бухгалтерских .xls (привет, xlrd 1.2), нормализацией грязных инвентарных номеров и автопушем в Google Sheets. Рассказываю про все грабли — от deadlock pandas vs xlrd до бага, который считал две разные железки одной

У носимых устройств есть парадокс: браслет измеряет ваши пульс, сон и активность, но готового открытого API для интеграции этих данных в сторонние системы (например, домашний мониторинг или локальную БД) производитель не предоставляет. Официальное приложение Xiaomi Mi Fitness показывает красивые графики, но данные остаются «запертыми» внутри мобильной экосистемы.

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

Эта статья - технический разбор пути от анализа сетевого трафика и настройки доверия к собственному CA до реверс-инжиниринга RC4-протокола Xiaomi, расшифровки AES/CBC-объектов из хранилища FDS и парсинга проприетарного бинарного формата сна.

При проектировании REST-интеграций часто возникает конфликт заголовков, когда и целевая система, и шина данных требуют дефолтный Authorization. В этой статье мы пошагово разберем, как перенастроить FESB на анализ кастомного заголовка для отдельной группы методов. Вы узнаете, как отключить стандартную проверку, распарсить Base64 с помощью Groovy и вернуть корректный HTTP-ответ.

Месяц назад мне в личку прислали фишинговую ссылку под MAX. Разобрал её, попутно вынес устройство протокола: опкоды, формат фрейма, флаги push-подписки, антибот-эвристики. Через две недели применил это знание к мирной задаче: собрал в том же мессенджере своего AI-секретаря, который пишет первым коллегам, бронирует столики и ведёт переписки до результата.

Всё через User API без регистрации, MCP-сервер на семь тулов, рабочий репозиторий с граблями. Делюсь инструкцией.

Мой знакомый Николай держит на Ozon магазин постельного белья. Со стороны всё нормально: оборот есть, товар продаётся, кабинет не пустует. А денег в конце месяца — нет. Не «мало», а непонятно куда они делись.

Я стал разбираться — и понял, что это не его частная беда. Полный P&L по каждому товару никто не считает: на каталоге в 500–2000 позиций это часы в неделю. Товар крутится в топе по обороту — но оборот ничего не говорит о марже: после возвратов и рекламы он годами уходит в минус, в полной слепой зоне. Инструментов на рынке хватает, но почти все просто показывают ещё одну P&L-таблицу — много цифр, красиво, и ровно ноль ответа на вопрос «и что мне теперь с этим делать».

Так появился SKUmind — сервис, который сводит прибыль по каждому SKU и говорит, что с ней делать. Под катом — почему я выкинул привычную для BI логику на правилах, как собрал консилиум из трёх AI-моделей разных вендоров с арбитратором, как реверс-инжинирил Ozon API двумя параллельными сессиями Claude и почему ревью кода теперь съедает 60–70% времени.

Вы можете замокать aiohttp.ClientSession._request и получить зелёный CI. Но этот тест всё ещё не доказывает, что у вас работает timeout. И не доказывает, что клиент переживёт обрезанный JSON. И не доказывает, что retry реально делает три HTTP-запроса через сокет.

В этой статье я прогоняю один и тот же сценарий через пять уровней тестирования внешнего API — от DI-заглушки до настоящего HTTP-сервера — и показываю, где каждый уровень врёт.