REST search API URI form

Question

Я реализую API поиска, который позволит осуществлять поиск по нескольким типам объектов в системе (клиенты, продукты и т. Д.). Какая форма URI будет предпочтительнее:

/clients/search 
/products/search 
... 

или

/search/clients 
/search/products 
... 

/клиенты,/продукты ресурсы уже существуют для других целей.

Edit:

Я не думаю, что это важно, но кажется, что он делает, так - поиск, вероятно, будет достаточно сложным, чтобы потребовать POST вместо GET

Спасибо,

Alex

Answer 1

это предложения выглядит вполне разумно: https://blog.apigee.com/detail/restful_api_design_tips_for_search так в соответствии с этим:

/clients/search 
/products/search 
... 

твитер использует не соответствует структуре:

• https://dev.twitter.com/docs/api/1.1/get/search/tweets
• https://dev.twitter.com/docs/api/1.1/get/users/search

Splunk предпочитает понятие search быть первым: http://docs.splunk.com/Documentation/Splunk/5.0.2/RESTAPI/RESTsearches.

Таким образом, эти примеры показывают, что нет единственного лучшего способа сделать это. Я думаю, было бы лучше пойти с первым примером, когда вы хотите ограничить свой запрос априори известными ресурсами. В противном случае используйте глобальный поиск - /search со всеми остальными, закодированными как параметры (см. Freebase API: https://developers.google.com/freebase/v1/search - у них есть свой язык для запросов ...).

Answer 2

Оба подхода ошибочны ИМХО.

Вопрос: что я получу, если я отправить следующий HTTP запросов к службе: уже существуют

GET /clients/search 
Host: service.org 

GET /products/search 
Host: service.org 

GET /search/clients 
Host: service.org 

GET /search/products 
Host: service.org 

Если/поиск и/продукты ресурсы, почему бы не использовать их и просто отправить необходимые параметры запроса при поиске? например:

GET /clients?gender=female&country=US 
Host: service.org 

Если клиентские запросы на обслуживание «/ клиент» будут реагировать со списком всех клиентов, если URI включает в себя параметры запроса службы будет реагировать с отфильтрованными результатами. Я думаю, что при создании таких выделенных ресурсов для поиска есть нулевое значение.

P.S. URI Щебета ужасны.

Answer 3

Если это ненадежный API, вам не нужно использовать слово «поиск» в вашем URI, поскольку продукт является ресурсом, а метод HTTP GET предоставляет глагол.Таким образом, вы можете сделать что-то вроде;

• GET /product/998827727/ (получить продукт по идентификатору)
• GET /product/?searchTerm=thingybob (найти продукт с поисковым термином)

Тем не менее, иногда условие поиска слишком сложно, поэтому вам нужна утилитой ресурс так, то вы что-то вроде POST /product-search/ или POST /product/search/ как продукт является основным источником