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

Короткий ответ Вложенный путь (/users/{id}/orders) уместен, когда ресурс логически не существует без родителя и к нему всегда обращаются в его контексте; плоский путь с фильтром (/orders?user_id={id}) лучше, когда ресурс самостоятелен и нужно выбирать его по разным критериям, не только по родителю. Как это работает подробнее вложенность пути отражает владение (ownership) — заказ существует только в контексте пользователя, который его создал. Но если нужно искать заказы одновременно по пользователю, статусу и дате — чисто вложенный путь усложняет комбинирование фильтров, а плоский с query-параметрами делает это естественно. Пример кода Что использовать на практике Рекомендация. глубокую вложенность (/users/{id}/orders/{oid}/items/{iid}) стоит ограничивать одним-двумя уровнями — иначе URL становятся громоздкими и ломкими при реорганизации модели данных. Часто практичнее делать GET /orders/{oid} без родителя в пути (ресурс сам по себе уникален по ID), используя вложенность только для создания (POST /users/{id}/o

Читать полностьюfiltering

Короткий ответ Версионирование через URL (/v1/...) — самое явное и простое для отладки, но "захватывает" версию во всех ссылках; через заголовок (Api-Version: 2) или content negotiation (Accept: application/vnd.myapi.v2+json) — чище с точки зрения REST (URL остаётся постоянным идентификатором ресурса), но менее заметно и сложнее для отладки curl'ом и кэширования прокси. Как это работает подробнее при версионировании через URL маршрутизация выбирает обработчик сразу по префиксу пути; при версионировании через заголовок один и тот же путь обслуживается разной логикой в зависимости от значения заголовка, что требует дополнительной диспетчеризации внутри приложения или на уровне API-гейтвея. Пример кода Что использовать на практике Рекомендация. выбор зависит от аудитории API: для публичного API с внешними интеграторами версия в URL снижает порог входа (видно в документации, легко протестировать вручную); для внутреннего API, тесно интегрированного с API-гейтвеем и кэшированием по URL, версия в заголовке мож

Читать полностьюapi-versioning

Короткий ответ Нужен длительный период параллельной работы старой и новой версии за одним бэкендом с общей бизнес-логикой (новая версия — это, как правило, другой слой трансляции данных, а не полностью отдельный сервис), прозрачный мониторинг реального трафика по версиям, явная коммуникация и поэтапное отключение старой версии только на основе наблюдаемого снижения трафика, а не фиксированной даты — конкретная длительность периода и критерии отключения зависят от состава и договорных обязательств перед интеграторами. Как это работает подробнее параллельная поддержка двух версий не должна означать дублирование бизнес-логики — обычно практичнее иметь единый внутренний слой данных/логики и два "адаптера" представления (сериализации) для v1 и v2 поверх него, чтобы изменения в бизнес-правилах не нужно было вносить в двух местах. Миграция данных схемы (если затронута структура БД) должна быть спроектирована так, чтобы оба адаптера могли корректно работать с одной и той же актуальной моделью данных одновременно (exp

Читать полностьюapi-versioning

Короткий ответ Нужен единый источник истины для контракта (OpenAPI/Protobuf-схема), версионируемый в репозитории и проверяемый автоматически (линтинг на breaking changes, contract-тесты типа consumer-driven contracts), который команда-провайдер не может изменить несовместимым образом без согласования с командами-потребителями; конкретный уровень строгости процесса зависит от числа потребителей и частоты релизов. Как это работает подробнее schema-first подход означает, что изменения в API сначала описываются в схеме (и проходят ревью/автоматическую проверку на совместимость), и только после этого реализуются в коде — это даёт явную точку контроля перед тем, как несовместимое изменение попадёт в production. Contract-тесты (например, по модели consumer-driven contracts) позволяют потребителю зафиксировать ожидания от API провайдера в виде тестов, которые провайдер прогоняет в своём CI перед релизом, узнавая о поломке контракта до деплоя, а не после. Пример кода Что использовать на практике Рекомендация. автомати

Читать полностьюci

Короткий ответ Path-параметры — часть URL, идентифицирующая конкретный ресурс (/users/42); query-параметры — необязательные модификаторы запроса после ? (?page=2&status=active), используемые для фильтрации, сортировки, пагинации. Как это работает подробнее path-параметр обычно обязателен и однозначно определяет ресурс в иерархии URL; query-параметры опциональны и не меняют "адрес" ресурса, а уточняют, какую выборку или представление вернуть. Пример кода Что использовать на практике Рекомендация. если без параметра запрос не имеет смысла (например, ID пользователя) — это path-параметр; если параметр можно не указывать и получить разумный результат по умолчанию (фильтр, лимит) — это query-параметр. Такое разделение упрощает кэширование и генерацию документации (OpenAPI). Подводные камни Риски. засовывать в path опциональные фильтры (/users/active/42), что усложняет маршрутизацию и делает URL негибким; передавать идентификатор ресурса как query-параметр (/users?id=42), когда это должен быть path-параметр, что пу

Читать полностьюpath-parameters

Короткий ответ HATEOAS (Hypermedia as the Engine of Application State) — принцип, при котором ответ API включает ссылки на доступные дальнейшие действия/ресурсы, позволяя клиенту "навигировать" по API динамически, а не хардкодить все URL заранее; для большинства внутренних и даже публичных API практическая польза ограничена по сравнению с ростом сложности, и решение внедрять его зависит от того, насколько клиентам нужна такая динамическая навигация. Как это работает подробнее вместо того чтобы клиент заранее знал, что после получения заказа со статусом "ожидает оплаты" нужно обратиться к /orders/{id}/pay, сервер включает в ответ ссылку с этим URL (и, возможно, только если действие действительно доступно в текущем состоянии) — клиент просто следует ссылкам, а не хардкодит бизнес-логику переходов. Пример кода Что использовать на практике Рекомендация. HATEOAS добавляет реальную ценность, когда переходы между состояниями ресурса действительно сложны и часто меняются, а разные клиенты (в том числе написанные не в

Читать полностьюapi-design

Короткий ответ Middleware — это слой кода, который выполняется для каждого (или группы) HTTP-запроса до и/или после основного обработчика; его используют для сквозной функциональности — логирования, аутентификации, CORS, обработки ошибок, замера времени запроса. Как это работает подробнее запрос проходит цепочку middleware по порядку их регистрации перед тем, как попасть в обработчик маршрута, а ответ проходит ту же цепочку в обратном порядке — так middleware может модифицировать и запрос, и ответ. Пример кода Что использовать на практике Рекомендация. middleware удобно для логики, общей для всех (или многих) эндпоинтов — не нужно дублировать код проверки токена или логирования в каждом обработчике отдельно. Но не всякая сквозная логика должна быть middleware — если проверка специфична для конкретного эндпоинта (например, доступ к конкретному ресурсу), лучше использовать dependency/декоратор на уровне обработчика. Подводные камни Риски. помещать в middleware тяжёлую бизнес-логику, которая должна зависеть от п

Читать полностьюcross-cutting-concerns