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

Пользователь нажал кнопку, сеть пропала, а браузер не знает, дошёл ли запрос до сервера. Повторите запрос — можно получить дубль. Не повторяйте — потеряете действие.

Показываю схему, которая решает обе проблемы: API без toggle, ключ идемпотентности в PostgreSQL, очередь в IndexedDB, Service Worker и проверка офлайна в Playwright. Это не полный offline-first — только защита действий в момент обрыва связи.

За три дня вокруг Jev выросла маленькая экосистема: браузерный агент искал авиабилеты за семь секунд, разработчики собрали торгового бота, фильтры контента и даже Tesla FSD. Но Jev не пишет текст. Его API выбирает ответ из пространства, которое заранее задало приложение.

Я разобрал документацию TypeSafe, код jev-ultrafast, опубликованную трассу семисекундного прогона и сто первичных или близких к ним источников. В статье — контракт Noul, Choice и Score, вызов API, цена, устройство браузерного агента и 15 ранних кейсов с границами их доказательности.

Главный вопрос простой: где узкий слой решений действительно выигрывает у обычной LLM, а где валидный ответ всё ещё оказывается просто не тем ответом?

Мы выпустили очередной релиз NEOMSA ESB. Фокус этого цикла — состав поставки: мы прошли по всем контурам сборки, сформировали SBOM, устранили уязвимости уровня Critical и High и зафиксировали версии так, чтобы они не «уехали» при следующей сборке.

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

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

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

У Codex CLI нет переменной «подставь свой URL»: OPENAI_BASE_URL он молча игнорирует и уходит в api.openai.com. Единственный путь — секция model_providers в config.toml, и в ней есть что сломать.

Собрал минимальный рабочий конфиг и девять способов его испортить: wire_api = “chat”, который больше не поддерживается; base_url без /v1, после которого в терминал прилетает HTML; supports_websockets на прокси без WebSocket; ключ открытым текстом в конфиге. Каждую ошибку воспроизвёл на версии 0.154, тексты приведены как есть.

В конце — сколько токенов стоит ответ из одного слова (спойлер: почти пятнадцать тысяч на входе) и загадка с кэшем на второй реплике, которую я пока не разгадал.

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

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

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

Путешествие редко состоит из одной операции: нужно совместить транспорт, даты, жилье, бюджет и иногда несколько пассажиров. Поэтому в начале лета мы открыли сервисы Туту для ИИ-агентов через Model Context Protocol (MCP), а в августе дали эту инфраструктуру участникам всероссийского хакатона.

Рассказываем, зачем вообще тревел-сервису MCP, что на нем начали собирать разработчики и какие ограничения у агентного подхода уже видны.

Собрал 6 сервисов с бесплатным или стартовым доступом к LLM API и проверил их. Какие модели реально работают, что дают после регистрации, сколько уходит баланса и какие лимиты встречаются — всё на реальных запросах.

Тестирование API часто сводится к одному: отправить запрос и убедиться, что сервер ответил 200. На собеседовании этого хватает на пару минут, а в проде именно здесь всплывает то, чего статус-код не ловит: чужой заказ в ответе, молчаливый 500 вместо ошибки валидации, товар, который не списался со склада.

Разберём 20 базовых проверок, которые отличают QA, тестирующего API, от того, кто просто дёргает ручки: успешный ответ, входные данные, ошибки, доступ и состояние системы — на одном сквозном сценарии, с примерами на curl и в Postman. Начинающий выстроит последовательность, опытный сверится и поймёт, куда расширять набор тестов.

Начну со сцены, которую видел каждый, кто эксплуатировал платёжный сервис хотя бы год.

Клиент нажимает «Оплатить». Приложение отправляет POST /payments. Проходит пять секунд, и HTTP-клиент падает по таймауту. Ретрай-политика, которую кто-то настроил год назад по гайду, ждёт двести миллисекунд и отправляет запрос ещё раз. Через минуту клиент видит в выписке два списания.

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

Первый вывод: надо выключить retry на POST. Хорошо, выключили. Теперь у нас платежи, про которые никто не знает, прошли они или нет. Поддержка разбирает их руками. Ущерб никуда не делся, он просто переехал на другой счёт.

Второй вывод: надо добавить заголовок Idempotency-Key. Добавили. Дедупликацию сделали в middleware поверх Redis. Через полгода двойное списание случается снова. Потому что Redis пережил failover и потерял ключи. Или потому что повтор пришёл через сутки из файла клиринга, а в файле никакого HTTP-заголовка нет.

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

Retry сам по себе всего лишь тактика. Он работает там, где контракт уже есть. Без контракта retry не делает систему устойчивее. Он делает её быстрее ломающейся.

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

Игра стоит в Steam 3299 ₽, ключ на маркетплейсе — 843 ₽. Вывод очевиден: ключ выгоднее вчетверо.

Я тоже так думал, пока не начал считать всерьёз. Оказалось, что при таком сравнении ответ неверен примерно в трети случаев, а иногда неверен катастрофически: есть игры, где «выгодный» ключ дороже Steam на 67%.

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

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

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

Типовую задачу проксирования трафика на базе заголовков и тела HTTP-запроса теперь можно решать напрямую с помощью предикатных локейшенов в NGINX.

До версии 1.31.5 для этого применяли тяжелые скрипты (медленно) и лабиринты из редиректов (неудобно). Теперь можно создать блоки location на базе любой переменной. В этом блоге разбираем методики чтения запроса и показываем примеры паттернов конфигурирования NGINX, которые вы можете применять для любого API или AI-трафика.

Своих MCP‑серверов у нас два: один к Битрикс24, второй к нашей системе заявок Okdesk. К Copilot оба подключены штатным путём, по документации Microsoft. Я Александр Жогов, основатель ИТ‑компании «+Альянс».

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

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

Breaking change в REST API часто обнаруживают слишком поздно — уже на интеграционном стенде. Разберём, какие риски можно поймать раньше, где помогают OpenAPI и consumer contracts и почему зелёные проверки ещё не гарантируют совместимость со старым клиентом.

Как я собрал бесплатный сервис метаданных книг на Java и Spring Boot — с EAV/Pivot-схемой БД вместо ALTER TABLE на каждое новое поле, агрегацией нескольких открытых источников. Плюс обновлённый плагин для Obsidian.

У Telegram-бота может быть только один активный webhook. У меня при этом появились три независимых сценария: поддержка пользователей, управление небольшим магазином и внутренние административные команды. Склеивать их в один процесс не хотелось, заводить отдельного бота под каждый сервис — тоже.

Пока я выбирал архитектуру, переезд панели с одного домена на другой неожиданно провёл бесплатный chaos test: Telegram продолжил отправлять updates на старый адрес, получил 301 Moved Permanently и перестал доставлять сообщения. В очереди зависло шесть updates, а со стороны пользователей бот просто замолчал.

В статье разберу диагностику этого инцидента и устройство небольшого open-source router на FastAPI и Redis: с декларативными правилами, дедупликацией, надёжной очередью, retry и HMAC-подписью внутренних запросов.

Проверил 6 AI API-сервисов с бесплатным доступом: VyceAI, Experiential, Dahl, APInex, ModelRouter и TokenForge. Сравнил доступные модели, стартовые лимиты, RPM и поведение API на практике.

Перевод по СБП — это не одна стрелка между двумя сервисами, а лимиты, антифрод, идемпотентность, НСПК, Kafka и уведомления. Я попробовал собрать этот сценарий не на вайтборде, а в виде интерактивного потока — и сразу нашел несколько дыр в архитектуре.

Разработчик приложил к тикету свой токен целиком — чтобы ошибку авторизации можно было воспроизвести. Ошибку починили, тикет закрыли, токен так и остался в задаче, которую видит вся команда и подрядчики.

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

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