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

Кванты, ИИ и российский рынок: почему рынок растёт против логики и как построить свою стратегию

Что происходит на финансовом рынке? Почему российские индексы растут, несмотря на череду негативных новостей? Можно ли собрать свою торговую стратегию с помощью ИИ — или это очередной хайп? Зачем вообще нужен квантовый подход, и что он даёт "простому" инвестору?

Ответы искали в живой дискуссии — инвестиционный советник Юлия Кузнецова, руководитель отдела количественного анализа, сооснователь проекта Quant Researcher Борис Беляков и продакт-менеджер «Финам Trade API» Эмиль Казакбаев. В выпуске на практике обсуждаются не только классические инвестиционные идеи, но и современные способы построения стратегий на данных и алгоритмах.

Собрали ключевые мысли эфира — без «секретных формул» и иллюзий лёгкой прибыли, только реальные вызовы и рабочие подходы:

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

• Нет универсальной стратегии для любого времени
  Даже самая красивая идея требует проверки на истории и понимания условий, при которых она перестаёт работать.

• Доходность не бывает без риска
  Любой высокий результат — плата за принятые риски. Нет магической нормы доходности: каждая стратегия уникальна по профилю риска и горизонту.

• Есть множество рабочих подходов
  Факторные модели, статистический арбитраж, трендовые и momentum-стратегии — каждый метод актуален в своём режиме и со своими ограничениями. Универсальных подходов не бывает.

• ИИ и анализ новостей — всего лишь инструмент
  Автоматизация через Skills, API, ИИ-ассистентов сильно помогает анализу. Но ИИ эффективен только как надстройка над вашей логикой, а не как замена головы и системности.

⚡️ В выпуске эксперты отдельно разбирали, почему российский рынок растёт не по классическим экономическим причинам; как меняется “баланс сил” между ОФЗ, акциями и валютой; что происходит с экспортёрами на фоне ослабления рубля и почему результат всегда совокупный эффект разных, часто неожиданных факторов.

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

Полный выпуск — где больше практики, дебатов и кейсов — смотрите на любой удобной платформе:

YouTube | Rutube | VK Видео

🤔 Как не терять requestId в логах не пробрасывая его через параметры методов?

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

import { scoped } from "di-scoped";

export interface IRequestContext {
  userId: string;
  requestId: string;
  serviceName: "mobile" | "desktop";
  version: number;
}

export const RequestContextService = scoped(
  class {
    constructor(readonly context: IRequestContext) {}
  }
);

export type TRequestContextService = InstanceType<
  typeof RequestContextService
>;

export default RequestContextService;

Согласно MVC, делается два слоя: View и Controller. На уровне view кладем requestId в контекст исполнения через RequestContextService.runInContext

import { inject } from "di-kit";

export class SocketViewService {
  readonly loggerService = inject<LoggerService>(TYPES.loggerService);
  readonly socketControllerService = inject<SocketControllerService>(TYPES.socketControllerService);

  public sendNewOrder = async (
    request: TRequest<{ room: string; orderId: string }>,
  ): Promise<TResponse<SendNewOrder>> => {
    this.loggerService.log("socketViewService sendNewOrder", { request });
    try {
      const data = await RequestContextService.runInContext(
//                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        async () =>
          await this.socketControllerService.sendNewOrder(request.data),
        request,
      );
      return { status: "ok", serviceName: request.serviceName, version: request.version, userId: request.userId, requestId: request.requestId, data };
    } catch (error: any) {
      this.loggerService.log("socketViewService sendNewOrder error", { request, error: errorData(error) });
      return { status: "error", error: VerificationError.getErrorMessage(error), errorCode: VerificationError.getErrorCode(error), serviceName: request.serviceName, version: request.version, userId: request.userId, requestId: request.requestId };
    }
  };
}

Voila! Во всех вложенных сервисах к записи в лог будет приложен идентификатор requestId. Дополнительно, этот код позволяет сериализовать ошибки так, чтобы передавать их по шине gRPC

import { inject } from "di-kit";
import { createLogger } from 'pinolog';

const logger = createLogger("socket.log");

export class LoggerService {

  readonly requestContextService = inject<TRequestContextService>(TYPES.requestContextService);

  private get context() {
    if (RequestContextService.hasContext()) {
      // в лог - только конверт IRequestContext; scoped-контекст. но дебаггеру виден весь запрос
      const { serviceName, version, userId, requestId } = this.contextService.context;
      return { serviceName, version, userId, requestId };
    }
    return {};
  }

  public log = (topic: string, ...args: any[]) => {
    logger.log(topic, ...args, this.context);
  }

}

BITCORD - объявляет конкурс на разработку: Валютный конвертер и Прогноз погоды!

Привет, Хабр! Мы ищем талантливых PHP-разработчиков, готовых создать два полезных, легковесных сервиса для нашей площадки. Главная фишка — ориентация на текстовый интерфейс (режим чата) и полная автономность кода.

Ниже представлены подробные требования к конкурсным работам.

Что нужно разработать?

Предстоит создать два независимых сервиса. Каждый сервис должен быть оформлен в виде одного самостоятельного PHP-файла, который внутри себя обращается к любым популярным сторонним API, но не привязан к жестким собственным эндпоинтам. Сервисы обязательно должны быть мультиязычными и возвращать результаты на том языке (локали), который передан в качестве входного параметра (ru, en, es...).

1. Сервис конвертации валют (converter.php)

• Интерфейс: Строго текстовый, адаптированный под логику чат-бота.

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

• Интеграция: Использование надежных внешних API для получения актуальных курсов валют.

2. Сервис прогноза погоды (weather.php)

• Интерфейс: Строго текстовый, структурированный для удобного чтения в чате.

• Объем данных: Сервис должен возвращать текстовую сводку погоды на:

  • Текущий день

  • Завтрашний день

  • Ближайшие 10 дней

• Интеграция: Использование популярных погодных API (например, OpenWeatherMap, WeatherAPI и т.д.).

Технические требования

• Язык программирования: PHP 8.x (чистый код, без тяжелых фреймворков вроде Laravel/Symfony на базовом уровне).

• Формат вывода: Только структурированный текст. Никакого HTML-структурирования или тяжелой графики - результат должен идеально смотреться в обычном CLI-терминале или окне мессенджера.

• Архитектура: Код должен быть чистым и легко встраиваемым в существующие чат-платформы.

• Безопасность: В каждом файле должна выполняться аутентификация по токену (Bearer Token) для защиты доступа к сервису.

Призы и сроки

• Победителю: Умная колонка Яндекс станция мини (с Алисой) или контракт на долгосрочное сотрудничество.

• Другие интересные решения: Денежный приз в криптовалюте мессенджера Bitcord (BTCD). Сумма будет зачислена на ваш кошелек в приложении Bitcord.

Сроки

• Дедлайн приема работ: 1 Октября 2026 г.

Как принять участие?

Опубликуйте ваш код на GitHub (публичный репозиторий) и отправьте ссылку в комментарии к этому посту или в мессенджер Bitcord на имя администратора @administrator. В README обязательно приложите пример передачи Bearer-токена в заголовках, краткую инструкцию по запуску и примеры текстовых команд.

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

х2 работы для ваших AI-агентов

За неделю выкатили сразу несколько релизов — собрали все в один пост. Суть у всех одна: агенты забирают на себя больше задач в ваших проектах.

Теперь можно:

1️⃣ Делиться с агентом файлами в Telegram 

Отправляете файл в чат вместе с запросом — агент сделает сводку по CSV с данными или найдет ошибку на скриншоте с логами.

Особенно удобно для тех, кто уже настроил ИИ-помощников в чатах поддержки.

2️⃣ Управлять облаком через команды

Выложили репозиторий со скиллами (инструкциями) для работы с Timeweb Cloud MCP. С ними агент получит готовые сценарии, например, как поднять сервер или настроить DNS. Меньше ошибок и лишних действий. 

В Claude Code скиллы ставятся как плагин в две команды, в Cursor, Codex и OpenCode — через npx skills.

3️⃣ Передавать агенту файлы через API

Добавили Files API — отдельный механизм для работы с файлами в API агентов. Он снял прежние ограничения по формату и размеру, и вы можете принимать любые файлы от своих пользователей.

Схема простая: пользователь вашего сервиса прикрепил файл в чате → сервис передал его агенту через API → агент ответил с учетом содержимого.

А еще выкатим новые локальные модели с низкой стоимостью — подробности скоро.

Нагрузить агента контентом →

API Т‑Банка и сертификаты Минцифры: как использовать без установки на сервере

У меня есть Tg-бот, в нём я подключил оплату через платёжные ссылки Т-Банка. В какой-то момент ссылки перестали создаваться, в логах ошибка:
SSL certificate OpenSSL verify result: self-signed certificate in certificate chain (19)

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

Варианты действий:

1. Подключить другую платёжку, которая (пока) не импортозаместила сертификаты.

2. Установить сертификаты на сервер (инструкция).
   Вам потребуется определённая степень доверия родному государству.
   На виртуальном хостинге так и вовсе может быть невозможно.

3. Собрать свою цепочку из сертификатов и использовать её только при запросах к API российских банков.
   Подходит для виртуального хостинга.

Третьему варианту меня научила нейронка, вот порядок действий:

1. Скачать сертификаты.

2. Распаковать два архива и загрузить на сервер вот эти файлы:
   russian_trusted_root_ca_pem.crt
russian_trusted_sub_ca_pem.crt
russian_trusted_sub_ca_2024_pem.crt

3. На сервере (у меня Ubuntu) скачать набор сертификатов от Mozilla:

   curl -fsSL -o cacert.pem https://curl.se/ca/cacert.pem
   

4. Собрать объединённую цепочку:

   cat \
      cacert.pem \
      russian_trusted_root_ca_pem.crt \
      russian_trusted_sub_ca_pem.crt \
      russian_trusted_sub_ca_2024_pem.crt \
      > ru-ca-bundle.pem
   

5. Проверить, что работает:

   curl -v --cacert ru-ca-bundle.pem https://mddc.tbank.ru/
   

6. Посмотреть сроки действия сертификатов:

   openssl x509 -in russian_trusted_root_ca_pem.crt -noout -subject -issuer -dates
   openssl x509 -in russian_trusted_sub_ca_pem.crt -noout -subject -issuer -dates
   openssl x509 -in russian_trusted_sub_ca_2024_pem.crt -noout -subject -issuer -dates
   

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

8. Добавить использование этой цепочки в коде запросов к российским банкам.
   У меня на php это выглядит так:

   $caBundlePath = __DIR__ . '/ru-ca-bundle.pem';
   if (!is_readable($caBundlePath)) {
       myerror("Tinkoff CA bundle is not readable", ['path' => $caBundlePath]);
       return false;
   }
   $ch = curl_init();
   curl_setopt_array($ch, [
       CURLOPT_URL => TINKOFF_INIT_URL,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_POST => true,
       CURLOPT_POSTFIELDS => $postDataJson,
       CURLOPT_HTTPHEADER => [
           'Content-Type: application/json',
           'Content-Length: ' . strlen($postDataJson),
       ],
       CURLOPT_SSL_VERIFYPEER => true,
       CURLOPT_SSL_VERIFYHOST => 2,
       CURLOPT_CAINFO => $caBundlePath,
   ]);
   
   $output = curl_exec($ch);
   

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

MCP 2026-07-28: что действительно изменилось

Главное изменение — MCP стал stateless на уровне протокола. Убрали обязательные initialize, initialized и Mcp-Session-Id. Версия протокола и возможности клиента теперь передаются в каждом запросе, а сведения о сервере можно получить через server/discover. Любой запрос может обработать любой экземпляр сервера — без sticky sessions и общего хранилища сессий. Состояние приложения никто не запрещает: просто передавай явные идентификаторы вроде browser_id в аргументах инструментов.

Что ещё важно:

1. Долгие операции получили нормальный жизненный цикл. Tasks позволяют вернуть taskId, а затем проверять состояние через tasks/get, передавать дополнительные данные через tasks/update и отменять работу через tasks/cancel. Но Tasks не появились с нуля — раньше это была экспериментальная часть ядра, теперь её переработали и вынесли в официальное расширение.

2. Протокол стал удобнее для эксплуатации. Заголовки Mcp-Method и Mcp-Name позволяют маршрутизировать запросы, не разбирая JSON. Появились стандартные подсказки для кеширования — ttlMs и cacheScope, а также единые поля для передачи OpenTelemetry Trace Context.

3. Переработано общение сервера с клиентом. Вместо произвольных server-to-client запросов сервер теперь может вернуть input_required, после чего клиент повторяет исходный запрос с ответом пользователя. Подписки на изменения вынесены в subscriptions/listen.

4. Extensions стали полноценной частью экосистемы. Новые возможности теперь можно развивать отдельно от ядра. Первые заметные расширения — Tasks и MCP Apps. Последнее позволяет серверу отдавать интерактивный HTML-интерфейс, который клиент показывает в изолированном iframe.

5. Есть важные ломающие изменения. Все результаты теперь содержат resultType. Roots, Sampling, Logging и старый HTTP+SSE объявлены устаревшими. Схемы инструментов получили полноценную поддержку JSON Schema 2020-12. Если ты пишешь MCP-клиент или SDK, этот пункт может оказаться важнее MCP Apps.

6. Авторизацию подтянули ближе к реальному OAuth/OIDC. Добавили проверку iss, привязку учётных данных к конкретному issuer и уточнили регистрацию клиентов и работу с refresh-токенами.

В сухом остатке: remote MCP перестал требовать обязательную протокольную сессию и стал гораздо больше похож на нормальный stateless JSON-RPC поверх HTTP. Для продакшена это означает более простое горизонтальное масштабирование, маршрутизацию и кеширование. Остальные изменения полезны, но в основном касаются новых возможностей и миграции клиентов.

• спецификация MCP 2026-07-28

• ключевые изменения в деталях

tg

Backend без хрупких интеграций: 5 материалов, которые вы могли пропустить

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

Эта подборка будет полезна тем, кто проектирует backend‑системы, работает с API, микросервисами, доменной моделью или просто регулярно сталкивается с вопросом: «как сделать так, чтобы архитектура не мешала разработке через полгода».

Собрали 5 материалов по теме:

1. Как фронтенд получает данные с сервера: лучшие практики 2026 
   _{О том, как backend и frontend договариваются через API, где уместны REST, GraphQL, BFF и Server Components, и почему «быстро отдать JSON» ещё не значит сделать удобный интерфейс для клиента.}

2. Domain‑Driven Design: полный гайд по моделированию домена в 2026 году
   _{Разбор DDD как способа управлять сложностью: единый язык, ограниченные контексты, агрегаты, сущности и границы между частями системы.}

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

4. Как построить надёжный обмен сообщениями в микросервисах: лучшие практики для enterprise
   _{Материал про асинхронное взаимодействие, очереди, события, идемпотентность, DLQ, мониторинг и типовые проблемы микросервисных интеграций.}

5. Архитектурные решения в backend: 5 практических приёмов
   _{О том, как принимать архитектурные решения без преждевременного усложнения: модульный монолит, YAGNI, порты и адаптеры, ADR и C4-диаграммы.}

А если хотите не только читать, но и разбирать темы с практиками, смотрите дайджест — там собраны бесплатные открытые уроки по разработке, архитектуре и инфраструктуре.

Прямая Web3-монетизация без посредников (Peer-to-Peer) для артистов на радио.

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

Задача была непростой. Нужно было объединить возможности мессенджера с его токеномикой и реализовать передачу медиаконтента (картинок, аудиофайлов, текстовых данных) на удаленный сервер в формате JSON. Для этого я написал серверную страницу на PHP, в которой реализовал весь необходимый API.

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

function isJpeg(string $data): bool
{
    return substr($data,0,2) === "\xFF\xD8";
}

function isMp3(string $data): bool
{
    if (substr($data,0,3)==="ID3") {
        return true;
    }

    return isset($data[1])
        &&
        ord($data[0])===0xFF
        &&
        (ord($data[1]) & 0xE0)===0xE0;
}

После получения данных нужно сразу определить что именно пришло - команда или файл:

if (preg_match('/^\/(help|bio|title|tracks|done)\b/i', $data))
{
    processCommand($db, $uuid, $data);
    exit;
}

if (isBase64($data))
{
    saveBinary($db, $uuid, $data);
    exit;
}

reply("Unknown command, please use /help.", false);

Описание профиля артиста и названия его треков передаются в текстовом виде используя специальный набор команд:

• /help - Show this help

• /bio text - Update artist biography

• /tracks - Show info of all tracks

• /title text - Update current track title

• /pay amount - Pay for service

• /done - Finalize current track

• Send JPG image to update artist image

• Send MP3 audio to update current track

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

1. артист отправляет фото профиля

2. артист отправляет описание профиля

3. артист загружает трек

4. артист отправляет описание трека

5. артист выполняет оплату сервиса

6. артист финализирует трек

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

МОНЕТИЗАЦИЯ

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

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

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

Таким образом, объединение двух разных сущностей, а именно интернет-радио с приложением для обмена сообщениями, является неким ноу-хау для оказания помощи в развитии молодых дарований. Лично для меня как для разработчика это отличный вызов и прекрасная возможность "пошевелить мозгами".

Если у вас появятся предложения, буду рад подискуссировать.

Новая лабораторная уже в субботу 27 июня! 👩‍🔬 Учимся проектировать API 🛠

Подробнее: https://debugskills.ru/content?article=labs/openapi-rest

Получить доступ: https://boosty.to/polnyistek

Эхо из прошлого: ошибки архитектуры могут "выстрелить" спустя годы (благодаря WebArchive)

Представьте: 8 лет назад была небезопасная архитектура с IDOR. Т.е. можно было получить доступ к документу просто зная его ссылку. А ссылки чудным образом попали в WebArchive (он же - Wayback Machine). Спустя время архитектуру поменяли и проблема ушла. Но, WebArchive всё помнит: ссылки уже успели сохраниться. И кто-то, спустя многие годы, публикует статью с указанием ссылок на WebArchive, где указаны персональные данные и платёжки клиентов. Внимание, вопрос: успокоит ли общественность реакция в стиле: "да это давно было, сервиса уж нет"?

Вот один из сохранённых по ссылке документа: он сохранился в Wayback Machine в 2018 и до сих пор доступен.

Самое печальное - некоторые компании не считают это угрозой. Для них это "фича, а не бага". Поподробнее о том почему компании не желают признавать проблему - в моей статье Wayback Machine как архив IDOR: как временные ссылки перестали быть временными.

Финальная книга на тему разработки публичных API: «API как искусство: разработка, поддержка, интеграция» [2025] — Сергей Константинов. Книга бывшего руководителя сервиса «Яндекс.Карты», которую можно назвать самой практичной, самой приземлённой и наиболее требовательной к квалификации читателя.

В отличие от книг, про которые я писал в предыдущих постах, она начинается сразу с девелоперской точки зрения. Как хороший архитектор, автор предлагает различные варианты реализации API, а потом говорит: «Миша, всё фигня, давай по новой» — и объясняет, почему.

Книжку нужно читать внимательно, так как автор часто приводит ссылки на свои же рассуждения и выводы из предыдущих глав. Однако для ленивого читателя он приводит методички по различным моментам проектирования API — например, «Вот 30 правил хорошего API», — тщательно поясняя, почему считает именно так.

Из интересного: поскольку автор работал в «Яндекс.Картах», он уделил целый раздел разработке SDK и UI-клиентских библиотек. Разработчикам, которые занимаются только server-side API, этот раздел, возможно, не нужен, но тем, кому это актуально, подобный материал нигде, кроме этой книги, не найти.

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

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

Поэтому я бы сказал так: первой книгой по проектированию API стоит читать «Проектирование веб-API» от Лоры Арно. А уже на эту базу — книгу Сергея с большим количеством практических примеров и кейсов из реальной жизни.

Это хорошая книга, которая заслуживает покупки и прочтения!

P. S. Возможно, в следующих изданиях книги стоит части 4 и 6 перенести в начало, вместо их текущей позиции. Тогда книжка будет идти от простого к сложному более предсказуемо.

Прочитал книжку, которую можно скорее назвать методичкой в силу её небольшого размера: «A Practical Approach to API Design» Кейта Кейси и Джеймса Хиггинботама, 2014 года. Это неплохой материал для понимания, что такое публичное API и каких принципов и паттернов стоит придерживаться при его проектировании.

Однако стоит уточнить, что книга по текущим меркам уже довольно старая — ей 12 лет. Поэтому некоторые главы посвящены рассуждениям, почему один подход лучше другого, причём эти сравнения сегодня во многом утратили актуальность: один стандарт проиграл, а другой де-факто стал общепринятым.

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

Читать этот материал в целом уже нет особого смысла, поскольку Лоре Арно в своей книге «Проектирование веб-API» прямо опирался на эту работу (и сам это указал). Поэтому лучше сразу уделить время книге Арно: в ней материал раскрыт в широком обучающем формате. К тому же книга Арно вышла в 2019 году и содержит более актуальную информацию.

Наконец-то поднял публичную демку Aximo на Hugging Face Spaces 🎙️

Это локальный speech-to-text API, который работает на CPU, использует Parakeet v3 и позволяет тестировать транскрибацию прямо из браузера через Swagger UI с записью с микрофона, о котором писал в одном из своих предыдущих постов.

• демо: https://ifif-aximo.hf.space/docs

• репозиторий: https://github.com/agent-axiom/aximo

Прочитал книжку «API Design Patterns» от бывшего разработчика Google — JJ Geewax, и это, на удивление, полностью ненужная книжка.

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

Особенно доставляет, что на большинство вопросов автор приводит несколько подходов, но не даёт никакого обоснования, где и когда нужно применять тот или иной подход. «Просто есть несколько вариантов — выбирай мудро» (с).

По самому предложенному варианту API тоже есть вопросы, ибо за свою 12-летнюю карьеру и знакомство с множеством реализаций API я ни разу не видел того, что предложил автор. Возможно, это внутренняя штука от Google, которая не стала широко используемой, но в Google её используют.

Ну и самое главное — в книге нет никакой целостности. Словно автор просто брал какую-то тему, писал про неё 6–8 страничек, потом брал новую тему и снова писал 6–8 страничек. И какой-то связи между этими главами нет.

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

Aximo — локальный STT API на Rust для CPU-only inference

Недавно сделал Aximo — self-hosted микросервис для speech-to-text, который можно запускать локально без облака и без зависимости от внешних SaaS.

Идея была довольно простая: хотелось собрать вменяемый STT API, который работает на CPU, поднимается как обычный сервис и при этом остается достаточно прозрачным с инженерной точки зрения.

В основе — Rust, локальный inference через Parakeet v3, HTTP API для обычной транскрибации и WebSocket-слой для realtime-сценариев. Из коробки также добавил Docker, OpenAPI и разбиение на несколько crates, чтобы проект не выглядел одноразовой демкой и оставался удобным для дальнейшего развития.

На текущем этапе это скорее крепкий MVP, чем законченный production-ready продукт, но уже сейчас сервис можно запускать локально, тестировать на своих аудиоданных и использовать как основу для дальнейших экспериментов.

Из интересного: доработал Swagger, добавив возможность отправки записи с микрофона:

Репозиторий проекта: https://github.com/agent-axiom/aximo

Звёзды приветствую

Мне не так часто в последнее время попадаются книги, где есть что-то ценное, кроме пары идей, которые автор повторяет по 10 раз разными словами. Однако книга «Проектирование веб-API» от французского разработчика веб-стандартов и публичных API Арно Лоре прямо сильно порадовала. 

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

Отдельно автор уделяет внимание использованию формата OpenAPI (бывший Swagger), который автор сам и развивал как активный участник OpenAPI-сообщества. Это немного иронично, ибо автор опубликовал эту книгу в 2019 году, а в 2022 году ушёл работать в Postman, которые развивают фактически конкурирующий стандарт. 

В своей книге автор делится ссылками на разные ресурсы, которые помогают разрабатывать публичное API. Однако на текущий момент большая часть этих ресурсов либо закрыта, либо находится в заброшенном виде. Ибо ИИ сейчас неплохо решают вопросы «страха перед белым листом» и неплохо советуют по подходам. 

В общем, кто разрабатывает публичные API, эту книгу рекомендую прочитать, чтобы понять, что вообще стоит учитывать и какие подходы существуют. Мега-полезная книга.

p.s. делитесь своими книгами и ресурсами по проектированию api, которые вам понравились

Написал небольшой микросервис на FastAPI, помогающий взаимодействовать с блокчейном Litecoin для принятия платежей. Сервис напрямую подключается к любой ноде на протоколе ElectrumX.

Список нод можно взять здесь: https://1209k.com/bitcoin-eye/ele.php?chain=ltc
Либо же можно захостить свою ноду, но пока нам будет достаточно удалённой.

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

Можем взглянуть на исходный код и перейдём к обзору функционала.
https://github.com/CryptoWrapAPI/litecoin-wallet-rpc

Для начала нужно получить свой ключ к блокчейну, проще говоря, сид-фразу.
Но не каждая сид фраза подойдёт, вкратце, нужна сид фраза стандарта BIP39.
Такую сид фразу можно сгенерировать с помощью new_wallet.py

Для этого нам понадобится Python версии 3.12, потому что библиотека bip_utils пока что поддерживает только эту версию.

Mnemonic string: 
rather nasty bright aisle craft spare blood room village resource special region winter gesture despair slender tiger wall state fashion grass trophy crack monster

Master key (bytes): 865fcb279555a25bf50e2e33d37ef68b363b3eb322a68456609526f80be28a7e
Master key (extended): zprvAWgYBBk7JR8GkiSjUUwyhei9mSTEMd5ENS9xywYxsf6WLuFvq9eJjE7eFCjw3sT4AreK7cRiBgF4x8CiL5sPUhwZA3rBhFbKD1poA3iWQCg
Master key (WIF): T7ZBZxkT8ebmYHyz1vHdG9G4of2UPJm2hVky1x19kX2xtQSKKCu4

Далее для деривации (создания отдельных адресов для принятия платежей) нам понадобится extended мастер-ключ.

Отправляем его вместе с account index и address index на эндпоинт /derive (запустим тест python tests/test_derive.py)

Индексы мы можем представить как координаты адреса по оси X и Y

============================================================
TEST: Address Derivation
============================================================
XPRV: zprvAWgYBBk7JR8GkiSj...
Account index: 0
Address index: 0

Status: 200
Response:
{
  "address": "ltc1qt25zdkgj4shgyp4xw770hsjtdph6kn70zz8h06",
  "account_index": 0,
  "address_index": 0,
  "chain": "external"
}

✓ Derived address: ltc1qt25zdkgj4shgyp4xw770hsjtdph6kn70zz8h06
============================================================

Теперь этот адрес кошелька можно отправить клиенту нашего сервиса.

Чтобы проверить, поступил ли платеж, мы можем обратиться к методу get_history
https://electrumx.readthedocs.io/en/latest/protocol-methods.html#blockchain-scripthash-get-history

// В этом примере адрес начинается с tltc1 вместо ltc1 
// Потому что это testnet блокчейн :)
// Сменить testnet/mainnet можно в .env

  "tltc1qayq6ppmzztpgy354r45lkp8vjdafnhtf0yhutm": {
    "transactions": [
      {
        "tx_hash": "6803c0769c89e2cd9bbbda1d1e8715c5b11c1e69f8f9a7d46c1cd6adc2103c6a",
        "height": 4672171
      },
      {
        "tx_hash": "10bdb766e7c8a42e468862a97b10260955fafe7a0fcd219f025b4dd105077e5e",
        "height": 4672208
      }
    ],
    "count": 2,
    "timestamp": "2026-04-10T01:23:37.448442+00:00"
  }

Мы видим две транзакции, height здесь - это номер блока, в который включена транзакция, если она всё ещё находится в мемпуле (ожидает подтверждения майнерами), то мы увидим -1 или 0.

Частота блоков в Litecoin составляет ~2 минуты. То есть примерно через 2 минуты транзакция будет включена в цепочку блоков.

Узнать детали транзакции можно с помощью эндпоинта /transactions
Там будет подробное описание транзакции, включая все "входы" и "выходы", количество отправленных монет, комиссию сети, заплаченную отправителем и так далее.

На этом у меня всё, спасибо за внимание!

От трейдера в хедж-фонде до продакт-оунера в Финаме: как искать «альфу», собирать портфели и зачем нужны хитрые ордера

Представляем новый выпуск подкаста.

Наш гость - Эмиль прошел путь от финансового инженера в Швейцарии до трейдера в алгоритмическом хедж-фонде, а теперь руководит развитием TradeAPI в Финаме. В этом интервью мы разбираем:

• что такое финансовый прайсинг и как ищут рыночную неэффективность («альфу»)

• как работает алгоритмический хедж-фонд изнутри и почему там ценят бесконфликтность больше, чем гениальность

• переход из трейдинга в продукт: чем занимается продакт-оунер в финтехе и как общение с клиентами формирует новый функционал

• что такое TradeAPI, кому он нужен и какие «хитрые ордера» появятся в будущем

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

• учеба в Швейцарии, работа ассистентом профессора и почему лучшие знания получаются не на лекциях, а в личном общении.

Полезно для всех, кто интересуется финансами, финтехом, трейдингом и карьерой в IT-продуктах.

Наш подкаст доступен на всех удобных платформах:

Youtube | Apple Podcast | Яндекс Музыка | Spotify | VK Музыка

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

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

Главная проблема: API First фокусируется на контрактах внешнего мира, что часто приводит к созданию DTO/Model классов, которые являются чистыми структурами данных без поведения (анемичная модель).

API First — это про контракты, а не про реализацию. Не позволяйте инструментам кодогенерации диктовать структуру вашей доменной модели!

Правильный workflow:

1. API Design First: Создайте/обновите OpenAPI спецификацию.

2. Генерация DTO: Сгенерируйте или создайте классы для API‑контрактов.

3. Projection First: Спроектируйте доменную модель независимо от DTO, фокусируясь на поведении и инвариантах.

4. Создание Mapping Layer: Напишите преобразователи между DTO и Domain Objects.

5. Реализация Application Service: Тонкий слой, который координирует работу домена.

Стек технологий, который помогает:

— MapStruct: Для автоматизации маппинга между DTO и Domain
— JUnit 5: Для тестирования доменной логики
— OpenAPI Generator: Для автоматической генерации DTO из спецификации
— ArchUnit: Для проверки архитектурных правил (например, запрет на анемичные модели)

// ArchUnit тест, проверяющий, что в доменных классах есть поведение
@ArchTest
static final ArchRule domain_models_should_have_business_methods = 
    classes()
        .that().resideInPackage("..domain..")
        .and().areAnnotatedWith(Entity.class)
        .should().containAnyMethodsThat(
            DescribedPredicate.describe(
                "have business methods", 
                method -> !method.getName().startsWith("get") && 
                         !method.getName().startsWith("set")
            )
        );

Почему моё Web API никогда не будет RESTful?

TL;DR потому мне не нужен динамический контракт.

Создатель архитектурного стиля REST Рой Филдинг — считает, что REST-архитектура должна соответствовать пяти обязательным ограничениям. У него довольно жёсткая позиция, что если API не выполняет хотя бы одного ограничения, то это не RESTful API. И тут ничего не поделаешь, как автор идеи считает, так и правильно. Далее я буду говорить, что api REST или не REST именно по Филдингу.

Но шутка в том, что хотя каждый уважающий себя бекендер знает про REST, почти никто не делает RESTful API. Но не потому что это недостижимый идеал, а потому что REST для апи, почти никому не нужен.

В смысле не нужен? А вот так, давайте взглянем на модель зрелости REST сервисов Леонарда Ричардсона. На первом и втором уровне находятся ресурсы и http-глаголы, вещь полезная, я понимаю их пользу и ничего против них не имею. А вот на третьем уровне мы видим hypermedia controls, о котором я бы хотел поговорить подробнее.

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

«REST API следует вводить без каких-либо предварительных знаний, кроме начального URI и набора стандартных типов данных. Все переходы состояний приложения должны определяться исходя из представлений или пользовательских манипуляций с ними, полученных клиентом от сервера»

— Рой Филдинг, Архитектурные стили и проектирование сетевых архитектур программного обеспечения.

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

Филдинг предполагал, что сервер может менять контракт как захочет, а клиент сможет его понять на основании гипермедиа. Вы встречали таких клиентов? На самом деле они есть, но про них мало кто знает. На практике в API HATEOAS не нужен ни программисту, ни программному клиенту. Программисту нужно описание контракта, с чем прекрасно справляются OpenAPI/Swagger, желательно автогенерённые из кода. А клиенту нужен четкий контракт, как создать товар или показать ленту. И меньше всего клиент хочет, чтобы контракт менялся, и тем более не хочет поддерживать средства обнаружения и подстройки под изменённый контракт.

В итоге перед программистом встаёт дилемма:

• Не делать HATEOAS. Но тогда его апи нельзя называть RESTful.

• ДелатьHATEOAS. Но тогда ему нужно будет "напихать ссылок" в ответы своего апи и поддерживать их просто чтобы называться RESTful. При этом, эти ссылки никто не будет использовать.

В итоге мы живём в мире, где бэкенд часто разрабатывают с использованием принципов REST, но при этом почти не существует RESTful апи. А те, что существуют, имеют пародийное название REST-like API или pragmatic REST. А 2-й уровень зрелости REST звучит так, как будто мы остановились на полпути к идеалу. Но ведь это не идеал: 3-й уровень зрелости часто бессмысленен или даже вреден.

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

А было бы круто, если бы кто-то придумал новый, хороший термин для архитектурных практик, которые бы взяли всё лучшее и полезное из REST применительно к современным Web-api. Тогда бы начинающие бэкендеры сразу осваивали актуальные подходы, а не книги Филдинга из 2000-х, как я когда-то.