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

Финальная книга на тему разработки публичных 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-х, как я когда-то.

Как войти в нужную дверь: API-ключ и как с ним работать

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

Чтобы использовать API-ключ, нужно:

1. Получить его в личном кабинете сервиса.

2. Добавить в запрос — обычно в заголовке Authorization.

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

Пример запроса в Node.js:

const axios = require('axios');

const API_KEY = process.env.MY_API_KEY;

axios.get('https://api.example.com/data', {

  headers: { 'Authorization': Api-Key ${API_KEY} }

})

.then(r => console.log(r.data))

.catch(e => console.error('Ошибка', e.response?.status));

В базе знаний Рег.облака поделились подробной инструкцией: как создать, подключить и защитить API-ключ. Заходите, сохраняйте и используйте :) 

В Рег.облаке стало доступно новое локальное решение для запуска и управления языковыми моделями LLM. Облачный сервис разворачивается за несколько минут и работает в изолированном окружении: данные и доступ полностью контролируются пользователем.

Что входит в образ:

• Ollama — фреймворк для запуска и управления LLM-моделями;

• Open WebUI — веб-интерфейс для работы через браузер;

• предустановленные модели Gemma 3, DeepSeek и Grok, с возможностью подключения моделей из Ollama и Hugging Face.

Основные возможности:

• интеграция через API во внутренние сервисы;

• подключение документов и баз знаний для контекстных ответов;

• параллельный запуск и сравнение нескольких моделей;

• плагины Open WebUI для работы с файлами и данными;

• работа с конфиденциальной информацией без передачи в публичные сервисы.

ИИ-ассистент доступен в конфигурациях с CPU и GPU. Для работы с несколькими моделями рекомендована конфигурация с NVIDIA A5000 (24 ГБ), 16 vCPU и 64 ГБ RAM. Заказать и протестировать сервер с ИИ-ассистентом можно уже сейчас на сайте Рег.облака.

Работа с Bluetooth Low Energy (BLE):основные протоколы и практические советы.

Почему BLE до сих пор “ТОП”?
Потому что даёт годами работать от батарейки -“таблетки”, держит связь в шумной среде и уже давно вышел за рамки «умных браслетов». Ниже - короткая, но практичная шпаргалка: что в BLE за что отвечает, где производительность «прячется», и на чём чаще всего спотыкаются.

BLE-стек делится на две большие части:
- GAP - «как знакомимся и подключаемся»: роли Central/Peripheral, сканирование, реклама (advertising) и параметры соединения.
- GATT/ATT - «как обмениваемся данными после подключения»: сервисы, характеристики, дескрипторы и операции чтения/записи/уведомлений. (PunchThrough, cardinalpeak.com)

Основное - по делу:
1) Реклама и роли
Legacy vs Extended Advertising: в Bluetooth 5 появилась расширенная реклама(Extended) и Periodic Advertising - удобно для «маячинга» и многоприёмников без подключения. (Novel Bits)Роли: Peripheral «светится» и ждёт подключения; Central сканирует и подключается. Это — GAP-уровень. (Punch Through)

2) Скорость, дальность и каналыPHY 1M - базовый; 2M PHY - больше скорость; Coded PHY (S=2/S=8) - для дальности и шумных сред; итоговый выбор - компромисс «скорость/дальность/надёжность». (RIOT Summit)
Для широковещания и энергосбережения в BLE 5.4 усилили «витаминку» для ESL/маячков: PAwR (Periodic Advertising with Responses), EAD (Encrypted AdvertisingData) и пр. - полезно для систем с множеством датчиков и электронных ценников. (Bluetooth Technology Website, silabs.com)

3) Пропускная способность: где «лежит» throughputATT MTU и Data Length Extension (DLE) увеличивают полезную нагрузку пакета (вплоть до ~251 байта данных на пакет) — ключ для высокой реальной скорости. (Punch Through, devzone.nordicsemi.com)
Настраивайте интервал соединения, slave latency и supervision timeout под задачу: меньше интервал — ниже задержка и выше пропускная способность, но больше расход батареи. Для потоков «почти-реального времени» ориентируйтесь на уведомления (см. ниже) и 2M PHY (если качество радио позволяет). Практические потолки зависят от хоста/ОС — тестируйте на целевых телефонах/ПК. (devzone.nordicsemi.com)

4) GATT-модель и событияNotify vs Indicate: оба «толкают» данные от сервера к клиенту; Indicate требует подтверждения на уровне протокола (надёжно, но медленнее), Notify — без подтверждения (быстрее, меньше оверхеда). Всегда добавляйте CCCD для (де)активации уведомлений. (Сообщество NXP, Thesis Pte Ltd, Reddit)Дизайн GATT: группируйте характеристики логически, минимизируйте количество сервисов и «глубокие» иерархии — это ускоряет discovery и упрощает кросс-платформенное поведение. (cardinalpeak.com)

5) Безопасность и приватностьLE Secure Connections (ECDH) — базовый стандарт для шифрования.Privacy: используйте RPA/Filter Accept List, а в BLE 5.4 — EAD для шифрованной рекламы (актуально для «маячков» с приватными данными). (Bluetooth Technology Website)

6) Мобильные ОС: подводные камниAndroid 12/13+: нужны runtime-разрешения BLUETOOTH_SCAN/CONNECT/ADVERTISE(диалог Nearby devices). Без них сканирование/подключение просто не начнётся.(Android Developers) iOS: в фоне реклама и сканирование ограничены — обычные рекламные PDU из бэкграунда не шлются; для сканирования в фоне задавайте конкретные UUID и включайте соответствующие background-моды. (Stack Overflow, Apple Developer)

7) Стек и инструментыДля «железа»: Zephyr Bluetooth Host (широко применим на MCU), NimBLE (легковесный стек от Apache Mynewt), BlueZ (Linux). Выбор стека влияет на доступность фич (DLE, Coded PHY, Periodic Adv). (docs.zephyrproject.org, Argenox)

8) Новшества, на которые стоит поглядыватьBLE 5.4 (PAwR, EAD) — для массовых устройств-«полок» и защищённой рекламы. (Bluetooth Technology Website)
Core 6.0: уточнения по таймингу кадра/интервалам в изохронных потоках (актуально для LE Audio/ISO). Если делаете аудио через BLE — изучите. (Bluetooth Technology Website)

Чек-лист для проектирования API

За 5 лет, что я проектирую API, вывела для себя шесть базовых принципов, которых стараюсь придерживаться:

1. Проектировать для потребителя

   • Ориентироваться на потребности клиентов API, а не на простоту реализации или устройство базы данных. Об этом, кстати, подробно написано в отличной книге Лоре Арно “Проектирование веб-API”.

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

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

2. Проектировать понятные API-схемы

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

   • Избегать обобщающих наименований, типа “flag”. Описывать в названии, какой бизнес-смысл несет этот параметр или метод. Например, флаг с признаком пустой упаковки можно назвать “isEmpty”.

   • Человек при прочтении схемы должен без дополнительной документации понять, зачем нужен этот API и что он делает.

   • Отдавать адекватные текстовые коды ошибок, из которых будет однозначно понятно, что поправить в запросе для успешного его выполнения. Например, отдавать не 400 BAD_REQUEST, а 400 PRODUCT_NOT_FOUND.

3. Принять конвенции и придерживаться их

   • Использовать везде либо snake_case, либо camelCase, либо kebab-case, не менять правила от метода к методу.

   • Стандартизировать формат ошибок - во всех методах отдавать их в одинаковой структуре.

   • Если это HTTP, то зафиксировать, в каких случаях какие коды ответов будут возвращаться. Например, иногда возвращается всегда 200, а потребители ориентируются только на тело ответа.

   • Договориться о формате версионирования API.

   • Стандартизировать типы данных: формат дат, UUID и пр.

4. Думать о безопасности, производительности и надежности

   • Использовать аутентификацию, авторизацию и ACL. Разграничивать доступ на уровне конкретных методов и даже параметров.

   • Оценивать количество запросов и объем ответов.

   • Индексировать БД по тем полям, по которым собираются выборки данных для API.

   • Использовать асинхронное взаимодействие, если задача на сервере выполняется ощутимое количество времени.

   • Делать обратную совместимость везде, где это возможно.

5. Документировать

   • Сначала писать документацию, а только потом разрабатывать. Такой подход минимизирует количество ошибок и проблем с API.

   • Помечать изменения тегами задач и, при необходимости, цветом.

   • Описывать логику работы методов/топиков/очередей. При необходимости добавлять диаграммы последовательности и маппинги данных.

6. Мониторить и анализировать

   • Понимать, какие методы как часто вызываются и как быстро работают. Как быстро обрабатываются сообщения в очередях и топиках, какое их количество и размеры. Это важно для принятия решений о дальнейших доработках API.

   • Смотреть в консоли разработчика на проде, как быстро отрабатывают те или иные запросы и т.д.

   • По возможности настраивать системы мониторинга и алертинга. Это помогает прогнозировать рост нагрузки и отслеживать эффективность системы.

У каждого API‑проектировщика со временем появляется свой набор правил. Было бы интересно сравнить — добавляйте свои пункты в комментариях.

Другие мои материалы можно почитать в телеграм-канале breakfront.

Задача о габаритном файле и ошибке

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

Условие

В компании «Доки.Онлайн» выкатили обновление: теперь пользователи могут загружать PDF-файлы с отсканированными договорами. Все работало отлично в локальной среде — разработчик протестировал загрузку больших файлов, убедился, что API обрабатывает их корректно, и спокойно отправил изменения в продакшн.

Но радость была недолгой. На боевом сервере при попытке загрузить файл система выдавала ошибку 413 Request Entity Too Large. Причем происходило это до того, как пользователь получал какой-либо отклик от самого приложения.

Разработчик Геннадий Завров начал искать причину. Он проверил логи всех четырех компонентов системы:

• фронтенда;

• API Gateway (определяет, в какой микросервис послать запрос);

• микросервиса загрузки файлов;

• микросервиса обработки документов.

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

Геннадий начал подозревать сетевые сбои, перегрузку API Gateway и баг в коде фронтенда. Однако простые тесты с маленькими файлами работали стабильно. Проблема проявлялась только при загрузке чего-то «потяжелее».

В какой-то момент он задал себе вопрос: а точно ли запрос доходит до приложений?

Задача

Почему при загрузке большого файла система возвращает ошибку 413, если сами сервисы даже не видят входящий запрос? Кто может остановить запрос еще до бэкенда?

Делитесь своим ответом в комментариях. А посмотреть полное решение можно в Академии Selectel.

Представлен ресурс (Context7 MCP - Up-to-date Code Docs For Any Prompt) из 9000 API с документацией для автоматического подключения к любым нейросетям. Поддерживается: Cursor, Windsurf, VS Code, Docker, Claude.

Безопасная разработка API на практике

Как устроен ваш цикл разработки приложений? Проверяются ли API на наличие уязвимостей до их публикации? И есть ли вообще для этого процесса какая-то методология?

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

Когда? 23 апреля в 14:00

Спикер: Динко Димитров, руководитель продуктового направления, Вебмониторэкс

Зарегистрироваться на мероприятие 

Ждем вас на вебинаре!

Как писать REST API — 9 правил

REST API (Representational State Transfer Application Programming Interface) — это архитектурный стиль взаимодействия между клиентом и сервером через HTTP. Он определяет принципы построения API, обеспечивая стандартизированный и эффективный обмен данными между различными системами.

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

2. POST запросы для загрузки/создания сущностей, PUT для изменения в сущности, а PATCH - для мелких изменений в сущности.

3. Наименование эндпоинтов. Должен присутствовать единый стиль, и желательно во множественном числе, ибо это более лаконичнее. Например, эндпоинт /users. Можно и единственное число использовать, но обосновано.

4. Иерархия. Нужно соблюдать единую иерархию для построения запросов. Конструкции /users/1/friends/3/items/4 будет неудобно использовать разработчикам клиентских приложений. Нужно избегать такую иерархию, нужно конкретно указывать что нам нужно, не перезагружать данными.

5. Соблюдайте версионирование API. Допустим: /api/v1/get_all_users и /api/v2/get_all_users. При выходе новой версии не всегда разработчики готовы переписать логику клиентских приложений, и для этого нам нужно разделять версии API

6. Чувствительные данные. Очень важный момент. Например, передача различных паролей в Query-параметрах запрещено, только в теле запроса.

7. Из 6 вытекает 7е правило: не логируйте персональные и прочие секретные данные. Было несколько случаев, когда из-за логирования параметров утекали данные пользователей.

8. Расширение ответов. Во-первых, не передавайте массивы в самом верхнем уровне ответа. JSON-ответ от сервера не должен быть массивом, только словарь (ключ-значение). Если мы будем возвращать список, в будущем нам будет неудобно расширить ответ сервера, добавив дополнительные параметры. А также иногда в API разработчики делают обязательные параметры, например помимо самих данных параметр success и error, чтобы клиентское приложение могло понять, что произошла ошибка, или наоборот, успешно выполнилось.

9. Работа с датой и временем. Есть два метода - использование Unix Timestamp (количество секунд прошедших с 1 января 1970 года). Это в какой-то степени более удобно для машины, но менее удобно для клиентского разработчика. И второй метод как раз делает формат даты и времени более понятным - это ISO 8601 (2025-04-05T12:00:00.100Z). Этот метод более удобный, т.к. мы понимаем дату и часовой пояс, точное время.

10. Бонусное правило, лично мое. Относится не только к REST API, но и в принципе к программированию. Пишите код так, как будто эта поэма, книга. Попробуйте сами поработать со своим API, будто вы его не писали. Разделение ответственности, единая точка отказа, Don't Repeat Yourself и даже Keep It Simple, Stupid. Все это конечно-же вариативно.

Полезные расширения для vsCode | просмотр JSON в виде дерева | Json Tree editor

Всем привет, этим постом начинаю серию постов с полезными плагинами для vsCode

🚀 Наименование: Json Tree editor

✍️Описание: расширение VSCode для визуализации данных JSON в виде дерева, с возможность выбора, перемещения и сортировки.

🔗 Ссылка на плагин: https://marketplace.visualstudio.com/items?itemName=GregChamblin.vscode-json-editor

Extension id: GregChamblin.vscode-json-editor

➕Плюсы:

• Можно работать с большими файлами json

• Есть отдельная кнопка на панели задач

• При перетаскивании в дереве элементов, сам json также изменяется онлайн

➖Минусы:

• Не выявлено

🚀Делитесь своими плагинами в комментариях.

#vsCode #JSON

Подписывайтесь на меня в телеграмм, там ещё много интересных плагинов @sa_chulan

[RFC] Открытый формат обмена данными об условиях кешбэка COIN

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

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

Предлагаемое название для подобного формата "COIN" (Cashback (details) Open Interchange - открытый обмен данными о кешбэке).

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

Демо-сервис базовых возможностей использования формата COIN Кашевар-онлайн