Когда я могу использовать параметры пути или параметры запроса в RESTful API?

Я хочу, чтобы мой RESTful API был очень предсказуемым. Как лучше всего решить, когда производить сегментацию данных с использованием URI, а не с помощью параметров запроса.

Мне кажется логичным, что системные параметры, поддерживающие разбиение на страницы, сортировку и группировку, должны быть после символа "?" Но как насчет таких полей, как «статус» и «регион» или других атрибутов, которые сегментируют вашу коллекцию? Если это также должны быть параметры запроса, каково эмпирическое правило, чтобы знать, когда использовать параметры пути?

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

Вот пример. Предположим, вы реализуете конечные точки RESTful API для объекта с именем Car. Вы должны структурировать свои конечные точки следующим образом:

GET /cars
GET /cars/:id
POST /cars
PUT /cars/:id
DELETE/cars/:id

Таким образом, вы используете параметры пути только тогда, когда указываете, какой ресурс извлекать, но это никоим образом не сортирует / фильтрует ресурсы.

Теперь предположим, что вы хотите добавить возможность фильтрации автомобилей по цвету в ваших GET-запросах. Поскольку цвет не является ресурсом (это свойство ресурса), вы можете добавить параметр запроса, который делает это. Вы должны добавить этот параметр запроса в свой запрос GET/cars следующим образом:

ПОЛУЧИТЬ /cars?color=blue

Эта конечная точка будет реализована так, чтобы возвращались только синие автомобили.

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

Ex. /two-words

Основной способ думать об этом предмете следующий:

URI - это идентификатор ресурса, который однозначно идентифицирует конкретный экземпляр ТИПА ресурса. Как и все остальное в жизни, каждый объект (который является экземпляром какого-либо типа) имеет набор атрибутов, которые либо не зависят от времени, либо являются временными.

В приведенном выше примере автомобиль - это очень осязаемый объект, у которого есть такие атрибуты, как марка, модель и VIN, которые никогда не меняются, а также цвет, подвеска и т. Д., Которые могут меняться со временем. Поэтому, если мы закодируем URI с атрибутами, которые могут изменяться со временем (временными), мы можем получить несколько URI для одного и того же объекта:

GET /cars/honda/civic/coupe/{vin}/{color=red}

А годы спустя, если цвет этой самой машины поменять на черный:

GET /cars/honda/civic/coupe/{vin}/{color=black}

Обратите внимание, что сам экземпляр автомобиля (объект) не изменился - изменился только цвет. Наличие нескольких URI, указывающих на один и тот же экземпляр объекта, заставит вас создать несколько обработчиков URI - это неэффективный дизайн и, конечно, не интуитивно понятный.

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

GET /cars/honda/civic/coupe/{vin}?color={black}

Итог - подумайте о полиморфизме.

В REST API вас не должны слишком беспокоить предсказуемые URI. Само предположение о предсказуемости URI намекает на неправильное понимание архитектуры RESTful. Предполагается, что клиент должен сам создавать URI, чего на самом деле не должно быть.

Однако я предполагаю, что вы создаете не настоящий REST API, а API, вдохновленный REST (например, Google Drive). В этих случаях практическое правило - «параметры пути = идентификация ресурса» и «параметры запроса = сортировка ресурсов». Итак, возникает вопрос, можете ли вы однозначно идентифицировать свой ресурс БЕЗ статуса / региона? Если да, то, возможно, это параметр запроса. Если нет, то это параметр пути.

НТН.

Однажды я разработал API, основным ресурсом которого был people. Обычно пользователи запрашивают фильтрацию, peopleпоэтому /people?settlement=urbanя реализовал , чтобы пользователи не вызывали что-то подобное каждый раз, /people/urbanчто позже позволило мне легко добавить /people/rural. Также это позволяет получить доступ к полному /peopleсписку, если он понадобится позже. Короче говоря, я хотел добавить путь к общим подмножествам

От сюда :

Псевдонимы для общих запросов

Чтобы сделать работу с API более приятной для среднего потребителя, рассмотрите возможность упаковки наборов условий в легко доступные пути RESTful. Например, приведенный выше запрос недавно закрытых билетов может быть упакован какGET /tickets/recently_closed

Вообще говоря, я обычно использую параметры пути, когда в ресурсе существует очевидная «иерархия», например:

/region/state/42

Если этот единственный ресурс имеет статус, можно:

/region/state/42/status

Однако, если «регион» на самом деле не является частью предоставляемого ресурса, он, вероятно, относится к одному из параметров запроса - аналогично разбивке на страницы (как вы упомянули).

Сегментация более иерархична и «симпатична», но может быть ограничивающей.

Например, если у вас есть URL-адрес с тремя сегментами, каждый из которых передает разные параметры для поиска автомобиля по марке, модели и цвету:

www.example.com/search/honda/civic/blue

Это очень красивый URL-адрес, который легче запоминается конечным пользователем, но теперь вы застряли в этой структуре. Допустим, вы хотите сделать так, чтобы в поиске пользователь мог искать ВСЕ синие автомобили или ВСЕ Honda Civics? Параметр запроса решает эту проблему, потому что он дает пару значений ключа. Итак, вы могли пройти:

www.example.com/search?color=blue
www.example.com/search?make=civic

Теперь у вас есть способ ссылаться на значение с помощью его ключа - либо «цвет», либо «сделать» в коде запроса.

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

www.example.com/search/make/honda/model/civic/color/blue

Надеюсь, это имеет смысл ..

Пример URL: /rest/{keyword}

Этот URL-адрес является примером параметров пути. Мы можем получить эти данные URL с помощью @PathParam.

Пример URL: /rest?keyword=java&limit=10

Этот URL-адрес является примером параметров запроса. Мы можем получить эти данные URL с помощью @Queryparam.