Как лучше передавать параметры в REST API?
В REST API можно организовать параметры как минимум двумя способами:
- Как часть URL-пути через аргументыˆ
/api/resource/parametervalue - В качестве аргумента запроса, query parameters:
/api/resource?parameter=value
Вопросы:
- Какие задачи лучше решать каким способом?
- Существуют ли способы параметризации API, которые я забыл?
Первый пример /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 не передаёт никакое тело, а должен передать только идентификатор объекта, которые стоит удалить. Ситуация аналогичная, вы можете это сделать, используя параметр маршрутизации. Почему именно его? Поскольку эти данные обязательные.