Я хочу, чтобы мой RESTful API был очень предсказуемым. Как лучше всего решить, когда производить сегментацию данных с использованием URI, а не с помощью параметров запроса.
Мне кажется логичным, что системные параметры, поддерживающие разбиение на страницы, сортировку и группировку, должны быть после символа "?" Но как насчет таких полей, как «статус» и «регион» или других атрибутов, которые сегментируют вашу коллекцию? Если это также должны быть параметры запроса, каково эмпирическое правило, чтобы знать, когда использовать параметры пути?
Ответы:
Лучшая практика для разработки RESTful API заключается в том, что параметры пути используются для идентификации конкретного ресурса или ресурсов, а параметры запроса используются для сортировки / фильтрации этих ресурсов.
Вот пример. Предположим, вы реализуете конечные точки RESTful API для объекта с именем Car. Вы должны структурировать свои конечные точки следующим образом:
GET
/carsGET
/cars/:idPOST
/carsPUT
/cars/:idDELETE
/cars/:idТаким образом, вы используете параметры пути только тогда, когда указываете, какой ресурс извлекать, но это никоим образом не сортирует / фильтрует ресурсы.
Теперь предположим, что вы хотите добавить возможность фильтрации автомобилей по цвету в ваших GET-запросах. Поскольку цвет не является ресурсом (это свойство ресурса), вы можете добавить параметр запроса, который делает это. Вы должны добавить этот параметр запроса в свой запрос GET
/carsследующим образом:ПОЛУЧИТЬ
/cars?color=blueЭта конечная точка будет реализована так, чтобы возвращались только синие автомобили.
Что касается синтаксиса, ваши имена URL должны быть полностью строчными. Если у вас есть имя объекта, которое обычно состоит из двух слов на английском языке, вы должны использовать дефис для разделения слов, а не верблюжий регистр.
Ex.
/two-wordsисточник
Основной способ думать об этом предмете следующий:
URI - это идентификатор ресурса, который однозначно идентифицирует конкретный экземпляр ТИПА ресурса. Как и все остальное в жизни, каждый объект (который является экземпляром какого-либо типа) имеет набор атрибутов, которые либо не зависят от времени, либо являются временными.
В приведенном выше примере автомобиль - это очень осязаемый объект, у которого есть такие атрибуты, как марка, модель и VIN, которые никогда не меняются, а также цвет, подвеска и т. Д., Которые могут меняться со временем. Поэтому, если мы закодируем URI с атрибутами, которые могут изменяться со временем (временными), мы можем получить несколько URI для одного и того же объекта:
А годы спустя, если цвет этой самой машины поменять на черный:
Обратите внимание, что сам экземпляр автомобиля (объект) не изменился - изменился только цвет. Наличие нескольких URI, указывающих на один и тот же экземпляр объекта, заставит вас создать несколько обработчиков URI - это неэффективный дизайн и, конечно, не интуитивно понятный.
Следовательно, URI должен состоять только из частей, которые никогда не изменятся и будут однозначно идентифицировать этот ресурс на протяжении всего его срока службы. Все, что может измениться, следует зарезервировать для параметров запроса как таковых:
Итог - подумайте о полиморфизме.
источник
В REST API вас не должны слишком беспокоить предсказуемые URI. Само предположение о предсказуемости URI намекает на неправильное понимание архитектуры RESTful. Предполагается, что клиент должен сам создавать URI, чего на самом деле не должно быть.
Однако я предполагаю, что вы создаете не настоящий REST API, а API, вдохновленный REST (например, Google Drive). В этих случаях практическое правило - «параметры пути = идентификация ресурса» и «параметры запроса = сортировка ресурсов». Итак, возникает вопрос, можете ли вы однозначно идентифицировать свой ресурс БЕЗ статуса / региона? Если да, то, возможно, это параметр запроса. Если нет, то это параметр пути.
НТН.
источник
Однажды я разработал API, основным ресурсом которого был
people. Обычно пользователи запрашивают фильтрацию,peopleпоэтому/people?settlement=urbanя реализовал , чтобы пользователи не вызывали что-то подобное каждый раз,/people/urbanчто позже позволило мне легко добавить/people/rural. Также это позволяет получить доступ к полному/peopleсписку, если он понадобится позже. Короче говоря, я хотел добавить путь к общим подмножествамОт сюда :
источник
Вообще говоря, я обычно использую параметры пути, когда в ресурсе существует очевидная «иерархия», например:
Если этот единственный ресурс имеет статус, можно:
Однако, если «регион» на самом деле не является частью предоставляемого ресурса, он, вероятно, относится к одному из параметров запроса - аналогично разбивке на страницы (как вы упомянули).
источник
Сегментация более иерархична и «симпатична», но может быть ограничивающей.
Например, если у вас есть URL-адрес с тремя сегментами, каждый из которых передает разные параметры для поиска автомобиля по марке, модели и цвету:
Это очень красивый URL-адрес, который легче запоминается конечным пользователем, но теперь вы застряли в этой структуре. Допустим, вы хотите сделать так, чтобы в поиске пользователь мог искать ВСЕ синие автомобили или ВСЕ Honda Civics? Параметр запроса решает эту проблему, потому что он дает пару значений ключа. Итак, вы могли пройти:
Теперь у вас есть способ ссылаться на значение с помощью его ключа - либо «цвет», либо «сделать» в коде запроса.
Вы можете обойти это, возможно, используя больше сегментов для создания своего рода структуры значения ключа, например:
Надеюсь, это имеет смысл ..
источник
Пример URL:
/rest/{keyword}Этот URL-адрес является примером параметров пути. Мы можем получить эти данные URL с помощью
@PathParam.Пример URL:
/rest?keyword=java&limit=10Этот URL-адрес является примером параметров запроса. Мы можем получить эти данные URL с помощью
@Queryparam.источник