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

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

Причин нашлось три, и каждой хватило бы одной. Запрос к графу знаний проходил через навык, но не мог вернуть его наружу. Граф отдавал пустую строку вместо честного «значения нет». А платформа искала навык не в том месте ответа, где он лежал. Когда починили все три, всплыло четвёртое звено.

Самое неприятное в другом. Ничего не падало и не ругалось. Всё, что опиралось на навыки, тихо считалось по темам и выглядело исправным.

Полный разбор с кодом и чек-листом для тех, кто строит похожие системы

API отвечает 200 OK, скрипт завершается без ошибок, а часть данных так и не попадает в базу. Разберём, как обычная пагинация может незаметно терять и дублировать записи, воспроизведём проблему на Python и посмотрим, как её обнаружить.

Привет, Хабр! Меня зовут Рома, я backend-разработчик в ЮMoney. Почти 10 лет наша команда занимается в том числе развитием публичного платежного API. Недавно мы запустили MCP-сервер (Model Context Protocol), который позволяет нейросетям (LLM) напрямую работать с платежами и счетами.

В процессе разработки и отладки мы быстро поняли, что проектирование API для языковых моделей кардинально отличается от привычной REST-архитектуры. В этой статье я хочу поделиться полученным опытом и мыслями. Технических деталей создания MCP-сервера здесь не будет: их в интернете и так хватает. Статья будет интересна разработчикам и архитекторам, которые планируют создавать публичные или внутренние MCP-серверы.

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

OpenAPI — это не только Swagger UI с описанием ручек. Спецификация может стать основой для множества повседневных задач фронтенд-разработчика:

Генерации TypeScript-типов для RTK Query, React Query и нативного fetch.

Генерации API-клиентов на примере orval.

Типизации запросов и ответов в BFF на Express.

Валидации запросов в обработчиках Express.

Генерации моковых данных и запуска mock-сервера.

Но что делать, если исходная спецификация содержит ошибки и всё это перестаёт работать? Здесь пригодятся валидация и подготовка спецификации — покажу, как хранить необходимые исправления в виде воспроизводимых правил с помощью openapi-modifier.

Подключить ИИ-агента к магазину еще не значит, что удастся поручить ему покупку. Я изучила открытые документации 424 компаний и продуктовв E-com и Финтех РФ.

У 232 нашлись API, MCP или A2A, но большинство подключений рассчитаны на бизнес и юр.лиц, а не на персональное использование. Разбираю, что доступно личным агентам и какие ограничения мешают. Прилагаю карту сервисов и таблицу с источниками.

Привет! Я Андрей Безруков, ведущий продакт-менеджер в Авито Рекламе. Мы с командой разработали публичный API, чтобы рекламные агентства и профессиональные рекламодатели могли автоматизировать работу с Авито Рекламой. В статье расскажу, как выбирали архитектуру, тестировали систему и упрощали подключение пользователей.

Пусть НЕ простят меня администраторы БД и архитекторы, если случайно прочитают... Сегодня я расскажу про внутреннюю архитектуру JMatrixPlatform, в которой реализовано эффективное извлечение сложных многоуровневых графов, больших объёмов.

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

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

Меня в Open Banking (открытом банкинге) интересует возможность собрать эту работу в одном сервисе. Клиенту нужен ответ на вполне конкретный вопрос: можем ли мы провести эти платежи и что произойдёт после подтверждения?

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

Я снимаю позиции статей, которые выходят не на моём сайте, а на чужих площадках: в отраслевых медиа, блогах, сообществах. Вебмастер и Search Console тут не помогают, они показывают позиции только по домену, который ты подтвердил как свой. Поэтому проверка позиций сайта у меня устроена по-простому: платный API отдаёт органическую выдачу по запросу, скрипт ищет в ней URL статьи и пишет место в базу.

Три месяца, с 7 июля по 13 октября 2026 года, скрипт исправно работал, и за это время в базе накопилось 42 477 строк замеров, и в отчётах они назывались «позиции сайта в Яндексе». 13 октября оказалось, что все они сняты с Google.

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

Один символ в адресе

У провайдера выдачи два адреса с одинаковым форматом ответа:

В ответы моделей Grok в API внедрят невидимый водяной знак с 7 ноября. SpaceXSI сообщила об этом в документации для разработчиков.

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

Меня всегда интересовало инженерное 3D-моделирование, но руки так и не дошли освоить его в должной степени. Зато я весьма неплохо научился работать с ИИ-агентами. Поэтому было решено перенести весь этот опыт в плоскость инженерных задач.Так появился плагин, через который LLM-агент работает в КОМПАС-3D: открывает модели, строит и правит детали и сборки, оформляет чертежи.

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

Проходим System Design Interview на 140%

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

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

Один платёж может трижды попасть в отчёт о продажах.

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

После проверки подлинности уведомления здесь нужны две отдельные проверки: получали ли мы это событие и учитывали ли уже саму оплату.

Например, в Stripe event.id — идентификатор события. В документации описана не только повторная доставка одного события: иногда создаются разные Event-объекты об одном объекте. Поэтому для однократной фиксации оплаты недостаточно проверять только event.id.

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

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

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

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

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

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

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

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

Личная подписка сотрудника на чужую карту, правило Anthropic про 50% владения, НДС налогового агента при покупке у иностранца и курс доллара, спрятанный в цене посредника. Разбираю по первоисточникам, что нужно компании для оплаты моделей по счёту и как считать реальную цену.