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

Тема достаточно обширная, поэтому предлагаю ее сузить до кейса:

Вот как в таких условиях сделать запрос и самое главное, в какую часть запроса какие данные разместить - давайте разбираться.
➖➖➖
💡
У нас есть 4 места, куда мы можем разместить наши данные:
1. Путь (Path)
2. Параметры запроса (Query)
3. Заголовки (Headers)
4. Тело (Body)
➖➖➖
Вернемся к нашему кейсу и определим, что куда класть, чтобы запросы были логичными, безопасными и удобными.

1. Bearer токен (авторизация)

Лучше всего передавать токен через заголовок Authorization. Это стандарт для REST API и безопасный способ передачи авторизационных данных.Пример:

Почему именно тут?
Потому, что:
- токен в заголовке недоступен в URL,
- не попадает в логи браузера или сервера, что минимизирует риск утечек.

2. Тип приложения, версия приложения, операционная система.

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

Мета данные мы передаем всегда в Заголовках.

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

3. Фильтры и сортировка данные по товарам.

Если мы видим слово фильтр или сортировка, то это однозначно должно у нас пойти в параметры запроса(query).

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

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

Надеюсь, что с примером стало понятнее 😉

➖➖➖

А теперь жду ваших рассказов за какой кусок у вас с командой холивары?