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

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

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

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

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

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

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

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

Большинство современных архитектурных подходов учат нас строить всё больше слоёв абстракции: контроллеры, сервисы, репозитории, адаптеры, транспортеры… Но что, если сложность системы растёт не из-за предметной области, а из-за самой архитектуры?

В этой статье я представляю FASA (Flat Adaptive Software ARchitecture) — спецификацию, которая предлагает радикально простой ответ: всего три сущности, строгие правила зависимостей и никаких промежуточных слоёв.

Вы узнаете, почему «плоский» граф компонентов может быть устойчивее многослойной архитектуры, как версионировать интерфейсы без боли, используя правило двойной поддержки (N-1) и где проходит граница между семантикой приложения и инфраструктурой — и почему это важно.

Спецификация языково-независима: примеры приведены для разных контекстов (Rust, сетевые протоколы, IPC), но правила применимы в любом стеке.

Ресторанная сеть из 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 из инструмента масштабирования в узкое место всей системы.

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

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

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

Берем официальный RustDesk (AGPLv3), не делаем форк, патчим его на лету в GitHub Actions при каждой сборке клиента. Поверх — российская инфраструктура: серверы в РФ, оплата по счёту юр.лицам, корпоративный SSO через Active Directory и Яндекс ID, защита от мошенничества на Android. К концу мая — стабильный релиз.

Меня зовут Артур Валиев. Я делаю не «решение для импортозамещения с сертификацией ФСТЭК» ради закупок. Просто работающий продукт, который я бы сам хотел использовать десять лет назад, когда сидел на саппорте у клиентов.

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