Александр Нездемина

Как правильно распределять данные в REST API

2026-06-16T20:13:47.410Z

Когда мы проектируем REST API, один из первых практических вопросов звучит так: какие данные куда класть в запросе?

У нас есть путь, query‑параметры, заголовки и тело — и каждый из этих элементов решает свою задачу.

В этой статье разберёмся на конкретном кейсе: витрина каталога товаров в мобильном приложении.

Кейс: витрина каталога и «глупый» фронт

Представим, что у нас есть фронт: iOS, Android и мобильный веб.
Фронт максимально "глупый": он просто ходит в мидл‑сервисы и хочет получить:

витрину с каталогом товаров
категории товаров
корзину пользователя

При этом, вместе с запросом фронт передаёт:

авторизационный токен
информацию о приложении (версия, тип устройства, операционная система)

Задача: понять, в какую часть HTTP‑запроса какие данные класть, чтобы запросы были логичными, безопасными и удобными для поддержки.

Четыре места для данных в HTTP‑запросе

В типичном REST API у нас есть четыре основных "слота", куда можно положить данные:

Путь (Path) — часть URL, которая описывает, к какому ресурсу мы обращаемся.
Параметры запроса (Query) — строка после ? в URL, используется для фильтров, сортировок и прочих модификаторов выборки.
Заголовки (Headers) — метаданные запроса: авторизация, формат данных, информация о клиенте.
Тело (Body) — основное содержимое: то, что мы создаём, изменяем или отправляем как сложный запрос.

Дальше разложим наш кейс по этим четырём местам.

Авторизационный токен: заголовок Authorization

Bearer‑токен (или любой другой токен авторизации) логичнее всего передавать в заголовке Authorization.
Это де‑факто стандарт для REST API и рекомендованный способ передачи авторизационных данных.

GET /api/v1/products
Authorization: Bearer eyJhbGciOiJIUz...

Почему именно заголовок:

токен не попадает в URL, а значит — не засветится в истории браузера или прокси
многие инструменты и библиотеки по умолчанию ожидают токен именно в Authorization
это согласуется с практиками OAuth 2.0 и большинством публичных API

Метаданные клиента: тип приложения, версия, ОС

Информация о том кто обращается, мобилка, веб. Это метаданные: они описывают не ресурс, а того, кто делает запрос.
Примеры:

тип приложения (mobile/web)
версия приложения
операционная система и её версия

Эти данные нужны серверу, чтобы:

принимать решения по фичефлагам (например, отключать функциональность для старых версий)
логировать и анализировать трафик по типам клиентов
внедрять ограничения: «для версии ниже 1.5 не отдаём новый тип карточек товара»

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

Пример:

X-App-Type: ios
X-App-Version: 1.2.3
X-OS-Name: iOS
X-OS-Version: 16.4

Исторически было принято использовать префикс X- для кастомных заголовков, но сейчас его применение считается устаревшей практикой.
Можно использовать более нейтральные варианты, например: App-Type, App-Version, Client-OS-Name.

Ключевой момент: не класть эти метаданные в тело, потому что:

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

Фильтры и сортировка: параметры запроса (query)

Когда речь идёт о фильтрации, поиске или сортировке, первый кандидат — query‑параметры.
Они позволяют явно описать, какую выборку мы хотим получить.

Пример запроса витрины:

GET /api/v1/products?sort=price&category=electronics&page=1&limit=20

Здесь:

sort=price — сортировка по цене
category=electronics — фильтрация по категории
page и limit — параметры пагинации

Рекомендации по фильтрам через query:

использовать понятные названия (price, category, brand, sort)
делать параметры консистентными: например, page/limit везде, а не page/perPage в одном методе и offset/count в другом.
для сложных фильтров применять единый формат (например, filter[field]=value или filter=field:op:value)

Когда фильтры уходят в тело запроса

Бывает, что фильтрация становится настолько сложной, что query‑строка становится:

слишком длинной
с трудом читаемой
плохо валидируемой и документируемой

В таких случаях разумно перенести фильтры в тело запроса и использовать POST для получения данных по сложному запросу.

POST /api/v1/products/search
Content-Type: application/json

{
  "sort": { "field": "price", "direction": "asc" },
  "filters": {
    "category": ["electronics", "appliances"],
    "price": { "gte": 1000, "lte": 5000 },
    "inStock": true
  },
  "page": 1,
  "limit": 20
}

Такой подход встречается, когда нужны:

сложные комбинированные фильтры
вложенные структуры
массивы значений и сложные условия

Правило, которое удобно держать в голове:
простые фильтры — в query, сложные и структурированные — в теле запроса.

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

Как правильно оформлять коды ошибок в API

2026-06-06T20:59:30.248Z

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

Из чего состоит хорошая ошибка?

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

Пройдёмся по этим пунктам.

Что произошло?

Ответ на этот вопрос обычно закрывают коды ответов 4xx и 5xx.
Например:
400 Bad Request — некорректные данные от клиента;
401 Unauthorized — пользователь не аутентифицирован (нет токена или он недействителен);
403 Forbidden — аутентификация есть, но нет прав доступа;
404 Not Found — ресурс не найден;
409 Conflict — конфликт состояния (например, такой email уже зарегистрирован);
422 Unprocessable Entity — данные приняты, но не прошли бизнес-валидацию;
429 Too Many Requests — превышен лимит запросов;
500 Internal Server Error — ошибка на стороне сервера;
503 Service Unavailable — сервис временно недоступен.

Но достаточно ли этого? В некоторых кейсах да, но иногда лучше вместе с кодом отправлять в теле ответа мнемонику, например: USER_NOT_FOUND, VALIDATION_ERROR, DUPLICATE_ORDER. Если это указать, клиенту будет проще разобраться и сделать обработку более персонализированной

Почему это произошло?

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

Что с этим делать?

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

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

Структура тела ошибки

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

Хороший базовый формат тела ошибки:

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка валидации",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "Неправильный формат email"
    }
  ]
}

code — машиночитаемая мнемоника, по которой клиент понимает, что делать.
message — человекочитаемое описание ошибки.
errors — массив, позволяющий вернуть все проблемы валидации за один запрос, а не по одной. Это особенно важно для форм, но лучше, чтобы контракт был единым для всех эндпоинтов.

Иногда вместо errors, если API простое и не требует детальной валидации, добавляют поле details или messageDetails, чтобы описать, как исправить ситуацию:

{  
 "code": "DUPLICATE_ORDER",  
 "message": "Заказ с id 12345 уже существует",  
 "messageDetails": "Заказ с номером 12345 уже существует. Если это ошибка, напишите в чат поддержки" 
}

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

{  
 "code": "DUPLICATE_ORDER",  
 "message": "Заказ с id 12345 уже существует",  
 "traceId": "abc-123-xyz" 
}

Частые антипаттерны, которые я встречаю на практике

1)Отвечать HTTP-кодом 200 на любые ответы, а реальный код ошибки передавать в теле ответа. Например:

{
 "code": "404",
 "message": "NOT FOUND"
}

2) Использовать разные форматы ошибок в разных эндпоинтах. В одном месте {"error": "..."}, в другом {"message": "..."}. В этом случае клиенту или сервису, который с вами интегрируется, придётся делать отдельный парсер для каждого варианта ошибки и затем унифицировать их.

3) Передавать стандартные сообщения вроде «что-то пошло не так» или технические ошибки типа NullPointerException в message. Такой формат не даёт никакой полезной информации.

Что фиксировать в требованиях при проектировании API

HTTP-статус должен соответствовать типу ошибки, а не всегда быть 200.
Указывать поле code с машиночитаемой мнемоникой.
Добавлять поле message без внутренних деталей и стек-трейсов.
Делать единый формат ошибки во всех эндпоинтах.
Если есть валидация, возвращать массив ошибок с описанием всех проблем, а не по одной.

И ключевое

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

Как использовать метод DELETE так, чтобы не получить по шапке?

2026-02-17T13:22:23.977Z

Метод DELETE под собой БАЗОВО подразумевает, что вызвав его - мы удалим полностью данные.

Но что делать, если есть сомнение: а действительно ли надо удалять ресурс? Может его надо обновить и просто скрыть без удаления, вдруг понадобится?

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

Кейс 1️⃣. Удаление банковской транзакции

Вы совершили отложенный перевод денежных средств в банк клиенте. Заявка в статусе на отправку, но деньги еще не ушли и вы хотите ее удалить.

Что делать?

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

➡️ можно сделать SOFT DELETE и просто прокинуть статус disable, а лучше поменять статус на "отменена" и тогда сохранится историчность.

Кейс 2️⃣. Удаление товара из системы в интернет-магазине.

У вас есть справочник товаров, которым управляют сотрудники. Они могут добавлять товары и удалять.

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

Что делать?

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

Мы проверяем, был ли товар добавлен хотя бы в 1 заказ.

➡️ Если был, то удалять такой товар нельзя и его нужно архивировать, так как, если мы его удалим, у нас умрут связи и это повлияет не только на историю заказов, но может затронуть финансовые операции, расчеты, а это очень больно, уж поверьте. Используем SOFT DELETE.

➡️ Если товар ни с чем не связан, то спокойно делаем DELETE.

Кейс 3️⃣. Удаление учётной записи пользователя в интернет-магазине

У вас есть учетная запись и функциональность по удалению этой учетки. Как ее реализовать?

Тут как и в предыдущем пункте - два варианта:

➡️ Если у пользователя не было покупок → можно удалить его аккаунт так:

DELETE /users/{id}

➡️ Если он совершал заказы → удалять нельзя, потому что его данные связаны с чеками, гарантиями, возвратами, заказами.

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

➡️ во всех случаях, когда Клиент удаляет учетку, я бы делал SOFT DELETE и еще добавил бы анонимность данных.

➖➖➖

А дальше дело техники

Как оформить запрос при DELETE и SOFT DELETE?

«Полное» удаление (DELETE)

• Метод: DELETE

• Endpoint: /resource/{id}

«Мягкое» удаление (SOFT DELETE)

• Метод: чаще PATCH или PUT

• Endpoint: resource/{id}, где передаём значение поля is_deleted = true или archived = true или status = "cancelled".

Пример:

PATCH /api/v1/products/123

Headers:
Content-Type: application/json

Body:
{
"is_archived": true,
"archived_at": "2025-02-26T12:00:00Z"
}

Почему при SOFT DELETE мы не используем метод DELETE?

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

⚡️⚡️⚡️

Не важно через какой метод вы это делаете, важно лишь то, что вы понимаете БАЗОВЫЕ принципы и логику, а еще используете мышление системного аналитика для решения таких задач.

Как правильно описать USE CASES, когда описываешь спеку на разработку UI интерфейса, чтобы команда не приходила потом с 1000 вопросов потом?

2025-05-21T07:36:36.605Z

Предлагаю сразу на примере:

У нас есть трекер калорий и него есть классная фича- сканирование штрих-кода для автозаполнения КБЖУ.

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

Тебе поставили задачу - описать требования к UI.

И один из способов это сделать – использовать USE CASES

Классически USE CASE выглядит так:

✔️ Название,

✔️ Актёры,

✔️ Предусловия,

✔️ Основной сценарий,

✔️ Альтернативные/ошибочные потоки,

✔️ Результат.

Теперь применяем это к нашему примеру:

✔️ Название:

UC‑1 Быстрое добавление продукта по штрих‑коду

✔️ Основной актёр:

Пользователь приложения

Системы:

Мобильное приложение, Back-сервис.

✔️ Предусловия:

- Приложение получило разрешение на доступ к камере.

- Устройство подключено к интернету.

✔️ Основной сценарий:

1. Пользователь открывает экран «Добавить продукт» и нажимает «Сканер штрих‑кода»;

2. Камера считывает шрих-код и отправляет POST /barcode/scan {code} на Backend;

3. Backend ищет у себя в кэше.

- Если найден, возвращает нутриенты и калории.

- Если не найден, то идет во внешних API.

4. API отвечает 200 OK, Backend нормализует данные, рассчитывает калории по формуле, кладёт результат в кэш.

5. Приложение показывает карточку продукта с БЖУ и кнопкой «Добавить в дневник».

✔️ Альтернативы:

2А. Камера не запустилась — приложение предлагает ввести код вручную;

3А. Внешний API вернул 404 — открывается форма ручного ввода нутриентов;

3B. API отвалилась по таймауту — показывается заглушка «Сервис недоступен», предлагается сфотографировать этикетку;

✔️ Постусловия:

- При успешном сценарии - продукт сохранён в дневнике, данные кэшированы;

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

➖➖➖

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

➖➖➖

Но что в этом подходе не так?

❗️А то, что front разработчику вообще не нужно знать, что происходит на стороне back, а back разработчику может и важно, что там делает фронт, но скорее нет = ИЗБЫТОЧНОСТЬ, которая и порождает за собой лишние вопросы со стороны команды.

➖➖➖

Так что же важно, когда мы описываем UI?

❗️Я в своей практике использую такой подход: разбиваю USE CASE на шаги и расписываю отдельно действия пользователя, и отдельно - системы, в рамках одного шага.

Вернемся к нашему примеру,

✔️ Название:

UC‑1 Быстрое добавление продукта по штрих‑коду

Шаг 1: Сканирование штрих-кода

Действие пользователя:

- Пользователь находится на экране добавления продукта;

- Пользователь нажал кнопку «Сканировать штрих-код».

Действие системы:

1. Система считывает штрих‑код и отправляет запрос:

Request: POST /barcode/scan {code} на Backend.

Response: JSON

- если данные получены, то перейти к шагу: отображение карточки продукта с БЖУ;

- если данные не пришли, то перейти к шагу: ввод данных вручную.

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

➖➖➖

Почему самообучение — не всегда выход?

Когда ты ищешь информацию в инете, то часто она уровня "обыватель".

В итоге:

✖️ неясно, что действительно нужно учить, а что — пустая трата времени;

✖️ нет обратной связи — ты не понимаешь, правильно ли всё усвоил;

✖️ нет структуры и целостного понимания.

Что даёт мой курс?

✔️ БАЗУ, которая нужна и для работы, и техсобесов,

✔️ Много практики,

✔️ Подробные комментарии к домашкам,

✔️ И главное — мой личный опыт и подходы, которые превращают тебя не просто в аналитика, а в незаменимого специалиста, которого ценит команда

ПОДПИСЫВАЙСЯ НА МОИ СОЦ СЕТИ:

ИНСТА | ТЕЛЕГРАМ | YOUTUBE | VK

%D0%A2%D0%AB%20%D0%9A%D0%A0%D0%A3%D0%A2%D0%9E%D0%99%20%D0%90%D0%9D%D0%90%D0%9B%D0%98%D0%A2%D0%98%D0%9A

2025-05-21T07:35:25.685Z

Как часто вы встречали такую крокозябру в текстах или в URL запросе?

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

Кто-то думает, что это защита шифрование SSL, но нет это не так.

✔️ Это encoding — это когда твоя строка превращается в безопасный формат для URL.

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

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

Там вы увидите вместо нормального слова - это

https://www.google.com/search?q=%D0%BC%D0%B0%D1%82%D1%80%D0%B5%D1%88%D0%BA%D0%B0

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

➖➖➖

Но, как понять, что закодировано в сообщении, если мы не знаем изначальный запрос?

✔️ Нам нужно сделать decoding – обратное превращение закодированной строки в обычную.

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

Самый сложный вариант - это найти таблицу UTF-8 и посмотреть, что значит конкретный символ.

Например, буква М будет выглядеть так %D0%BC

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

Сервисов много.

💾 Например, https://www.urldecoder.org/ru

✔️ переходим по ссылке,

✔️ вбиваем наши кракозябры,

✔️ нажимаем декодировать

🪄 вуаля, у вас нормальная строка

Го декодировать заголовок 🥂

ПОДПИСЫВАЙСЯ НА МОИ СОЦ СЕТИ:

ИНСТА | ТЕЛЕГРАМ | YOUTUBE | VK