Как лучше передавать параметры в REST API?
В REST API можно организовать параметры как минимум двумя способами:
- Как часть URL-пути через аргументыˆ
/api/resource/parametervalue - В качестве аргумента запроса, query parameters:
/api/resource?parameter=value
Вопросы:
- Какие задачи лучше решать каким способом?
- Существуют ли способы параметризации API, которые я забыл?
Ответы (1 шт):
Первый пример /api/resource/parametervalue используется когда вам параметр нужен как часть пути или привязки к чему-то. На пример возьмём контроллер для работы с материалами, и какие у него могут быть допустимые адреса:
api/material/createapi/material/get/all?name=p_name&price=123api/material/get/{id}api/material/{id}/update/nameapi/material/{id}/update/descriptionapi/material/{id}/update/priceapi/material/{id}/deleteapi/material/{id}/attachapi/material/{id}/detach
В чём суть? Когда вы используете параметр id, вы уточняете, для кого вы хотите выполнить то или иное действие. Так же, второй пример содержит query parameters, т.е. те, которые идут после амперсанда. Это значит, это они не обязательные. К пример, вы можете использовать их как часть фильтров для get запросов.
Для post запросов они в основном не используются или, по крайней мере, я не видел таких вариантов применения. Почему? Потому что параметры строки запроса передают некие данные на сервер. При выполнении post запроса вы и так передаёте данные, но уже в теле запроса. Да, для post запроса так же используются параметры маршрутизации (id в этом и подобных примерах api/material/{id}/detach), но вы так же можете их передавать просто в теле запроса, но это уже будет немного не по конвенциям REST Api.
Напомню, что основная разница между get и post запросом в том, что get запрос не может иметь тела запроса. Параметры запроса решают проблемы уточнения данных, которые вы хотите получить, соответственно, они не используются для post запросов.
В заключение, параметры запроса и параметры маршрутизации это разные вещи, которые делают примерно одно и то самое - передаю данные. Параметры маршрутизации используются для уточнения пути к объекту, с которым вы собираетесь работать, а параметры запроса используются больше как фильтры при неком запросе и являются не обязательными.
UPD: Что имеет смысл использовать при put, patch и delete запросах? Есть разобраться, то put запрос это как смесь между get и post и в основном предназначен для идентификации сервером намерений клиента, т.е., обновление неких данных. Есть ли смысл использовать тут параметры запроса? Думают нет, поскольку вам нужно просто передать данные для обновления в теле запроса и идентификатор объекта, которых хотите обновлять, а его, как было написано ранее, можно передать как параметр маршрутизации или так самое в теле запроса.
patch использует для обновления специальные инструкции, по этому тут так же не стоит ничего лишний раз придумывать.
delete не передаёт никакое тело, а должен передать только идентификатор объекта, которые стоит удалить. Ситуация аналогичная, вы можете это сделать используя параметр маршрутизации. Почему именно его? Поскольку эти данные обязательные.