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

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

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

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

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

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

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

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

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

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

1. Путь (Path) — часть URL, которая описывает, к какому ресурсу мы обращаемся.
2. Параметры запроса (Query) — строка после ? в URL, используется для фильтров, сортировок и прочих модификаторов выборки.
3. Заголовки (Headers) — метаданные запроса: авторизация, формат данных, информация о клиенте.
4. Тело (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, сложные и структурированные — в теле запроса.

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

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

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

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

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

Ответ на этот вопрос обычно закрывают коды ответов 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 без внутренних деталей и стек-трейсов.
• Делать единый формат ошибки во всех эндпоинтах.
• Если есть валидация, возвращать массив ошибок с описанием всех проблем, а не по одной.
  

И ключевое

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

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

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

Кейс 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, но в этом случае такой запрос не очевидно читается. И внутри придется делать дополнительную логику.

⚡️⚡️⚡️

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

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

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

Тебе поставили задачу - описать требования к 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

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

Кто-то думает, что это защита шифрование 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