Я ищу разумный способ представления поисковых запросов в виде RESTful URL.

Установка: у меня есть две модели, Автомобили и Гаражи, где Автомобили могут быть в Гаражах. Так что мои URL выглядят так:

/car/xxxx
  xxx == car id
  returns car with given id

/garage/yyy
  yyy = garage id
  returns garage with given id

Автомобиль может существовать сам по себе (отсюда и / автомобиль) или в гараже. Как правильно представить, скажем, все машины в данном гараже? Что-то вроде:

/garage/yyy/cars     ?

Как насчет объединения автомобилей в гараже yyy и zzz?

Как правильно представить поиск автомобилей с определенными атрибутами? Скажи: покажи мне все синие седаны с 4 дверями:

/car/search?color=blue&type=sedan&doors=4

или это должно быть / автомобили вместо?

Использование «поиска» там неуместно - что лучше / термин? Должно ли это быть просто:

/cars/?color=blue&type=sedan&doors=4

Должны ли параметры поиска быть частью PATHINFO или QUERYSTRING?

Короче говоря, я ищу руководство для кросс-модели REST URL дизайн и для поиска.

[Обновление] Мне нравится ответ Джастина, но он не охватывает случай поиска в нескольких полях:

/cars/color:blue/type:sedan/doors:4

или что-то типа того. Как мы идем из

/cars/color/blue

в случае нескольких полей?

Для поиска используйте строки запроса. Это совершенно ОТЛИЧНО:

/cars?color=blue&type=sedan&doors=4

Преимущество обычных строк запросов заключается в том, что они являются стандартными и широко понятными, и что они могут быть сгенерированы из form-get.

Дизайн привлекательного URL RESTful предназначен для отображения ресурса на основе структуры (структура, похожая на директорию, дата: article / 2005/5/13, объект и его атрибуты, ..), косая черта /указывает на иерархическую структуру, используйте -idвзамен.

Иерархическая структура

Я бы лично предпочел:

/garage-id/cars/car-id
/cars/car-id   #for cars not in garages

Если пользователь удаляет /car-idчасть, это делает carsпредварительный просмотр интуитивно понятным. Пользователь точно знает, где в дереве он находится, на что он смотрит. С первого взгляда он знает, что гаражи и машины взаимосвязаны. /car-idтакже означает, что он принадлежит вместе в отличие от /car/id.

Поиск

Поисковый запрос в порядке, как есть , есть только ваши предпочтения, что следует учитывать. Самое смешное происходит при объединении поисков (см. Ниже).

/cars?color=blue;type=sedan   #most prefered by me
/cars;color-blue+doors-4+type-sedan   #looks good when using car-id
/cars?color=blue&doors=4&type=sedan   #I don't recommend using &*

Или в основном что-нибудь, что не является косой чертой, как объяснено выше.
Формула: /cars[?;]color[=-:]blue[,;+&]*, хотя я бы не использовал &знак, так как он неузнаваем по тексту на первый взгляд.

** Знаете ли вы, что передача объекта JSON в URI является RESTful? **

Списки вариантов

/cars?color=black,blue,red;doors=3,5;type=sedan   #most prefered by me
/cars?color:black:blue:red;doors:3:5;type:sedan
/cars?color(black,blue,red);doors(3,5);type(sedan)   #does not look bad at all
/cars?color:(black,blue,red);doors:(3,5);type:sedan   #little difference

возможные особенности?

(!) Нивелируют строки поиска
Для поиска любых автомобилей, но не черный и красный :
?color=!black,!red
color:(!black,!red)

Регистрация поиск
Поиск красные или синие или черные машины с 3 -х дверей в гаражах ID 1..20 или 101..103 или 999 , но не 5 /garage[id=1-20,101-103,999,!5]/cars[color=red,blue,black;doors=3]
Вы можете построить более сложные поисковые запросы. (Посмотрите на соответствие атрибутов CSS3 для идеи соответствия подстрок. Например, поиск пользователей, содержащих "bar" user*=bar.)

Вывод

Во всяком случае, это может быть самая важная часть для вас, потому что вы можете сделать это , однако вы , как в конце концов, просто имейте в виду , что RESTful URI представляет собой структуру , которая легко понять , например , каталогов , как /directory/file, /collection/node/item, даты /articles/{year}/{month}/{day}.. И когда вы опускаете любой из последних сегментов, вы сразу знаете, что вы получаете.

Итак, все эти символы разрешены в незашифрованном виде :

• незарезервировано: как a-zA-Z0-9_.-~
  правило, разрешено как закодировано, так и нет, оба варианта использования эквивалентны.
• специальные символы: $-_.+!*'(),
• зарезервировано: ;/?:@=&
  может использоваться в незашифрованном виде для целей, которые они представляют, в противном случае они должны быть закодированы.

• unsafe: <>"#%{}|\^~[]`
  почему небезопасно и почему лучше кодировать: RFC 1738 см. 2.2

  Также см. RFC 1738 # page-20 для большего количества классов символов.

RFC 3986 см. 2.2.
Несмотря на то, что я ранее сказал, здесь есть общее различие делимеров, означающее, что некоторые «являются» более важными, чем другие.

• общие разделители: :/?#[]@
• суб-разделители: !$&'()*+,;=

More reading:
Иерархия: см. 2.3 , см. 1.2.3
Синтаксис параметра пути CSS URL-
адреса, соответствующий атрибуту CSS3
IBM: Web-сервисы RESTful - Основы
Примечание: RFC 1738 был обновлен RFC 3986

Хотя наличие параметров в пути имеет некоторые преимущества, IMO имеет некоторые перевешивающие факторы.

• Не все символы, необходимые для поискового запроса, разрешены в URL. Большинство знаков препинания и Unicode должны быть URL-адресами в виде параметра строки запроса. Я борюсь с той же проблемой. Я хотел бы использовать XPath в URL, но не весь синтаксис XPath совместим с путем URI. Поэтому для простых путей /cars/doors/driver/lock/combinationбыло бы целесообразно найти combinationэлемент ' ' в XML-документе двери водителя. Но /car/doors[id='driver' and lock/combination='1234']не все так дружелюбно.

• Существует разница между фильтрацией ресурса по одному из его атрибутов и указанием ресурса.

  Например, так как

  /cars/colors возвращает список всех цветов для всех автомобилей (возвращаемый ресурс является коллекцией цветовых объектов)

  /cars/colors/red,blue,green вернул бы список цветных объектов красного, синего или зеленого цвета, а не коллекцию автомобилей.

  Чтобы вернуть автомобили, путь будет

  /cars?color=red,blue,green или /cars/search?color=red,blue,green

• Параметры в пути труднее читать, потому что пары имя / значение не изолированы от остальной части пути, которая не является парами имя / значение.

Последний комментарий Я предпочитаю /garages/yyy/cars(всегда во множественном числе) /garage/yyy/cars(возможно, это была опечатка в первоначальном ответе), потому что она избегает изменения пути между единственным и множественным числом. Для слов с добавленными 's' изменение не так уж плохо, но изменение /person/yyy/friendsна /people/yyyкажется громоздким.

Чтобы расширить ответ Питера - вы можете сделать Поиск первоклассным ресурсом:

POST    /searches          # create a new search
GET     /searches          # list all searches (admin)
GET     /searches/{id}     # show the results of a previously-run search
DELETE  /searches/{id}     # delete a search (admin)

Ресурс поиска будет иметь поля для цвета, марки, модели, состояния гаража и т. Д. И может быть указан в XML, JSON или любом другом формате. Как и ресурс Car and Garage, вы можете ограничить доступ к поискам на основе аутентификации. Пользователи, которые часто запускают одни и те же поиски, могут сохранять их в своих профилях, чтобы их не нужно было заново создавать. URL-адреса будут достаточно короткими, чтобы во многих случаях их можно было легко обменять по электронной почте. Эти сохраненные поиски могут быть основой пользовательских RSS-каналов и т. Д.

Есть много возможностей для использования поиска, когда вы думаете о них как о ресурсах.

Идея объяснена более подробно в этом Railscast .

Ответ Джастина - это, вероятно, правильный путь, хотя в некоторых приложениях имеет смысл рассматривать конкретный поиск как самостоятельный ресурс, например, если вы хотите поддерживать именованные сохраненные поиски:

/search/{searchQuery}

или

/search/{savedSearchName}

Я использую два подхода для осуществления поиска.

1) Самый простой случай, для запроса связанных элементов и для навигации.

    /cars?q.garage.id.eq=1

Это означает, что запрашивать автомобили с идентификатором гаража, равным 1.

Также возможно создание более сложных поисков:

    /cars?q.garage.street.eq=FirstStreet&q.color.ne=red&offset=300&max=100

Автомобили во всех гаражах FirstStreet, которые не являются красными (3-я страница, 100 элементов на страницу).

2) Сложные запросы рассматриваются как обычные ресурсы, которые создаются и могут быть восстановлены.

    POST /searches  => Create
    GET  /searches/1  => Recover search
    GET  /searches/1?offset=300&max=100  => pagination in search

Тело POST для создания поиска выглядит следующим образом:

    {  
       "$class":"test.Car",
       "$q":{
          "$eq" : { "color" : "red" },
          "garage" : {
             "$ne" : { "street" : "FirstStreet" }
          }
       }
    }

Он основан на Grails (критерии DSL): http://grails.org/doc/2.4.3/ref/Domain%20Classes/createCriteria.html

Это не ОТДЫХ. Вы не можете определить URI для ресурсов внутри вашего API. Навигация по ресурсам должна быть управляемой гипертекстом. Хорошо, если вам нужны красивые URI и большое количество соединений, но просто не называйте это REST, потому что это напрямую нарушает ограничения архитектуры RESTful.

Смотрите эту статью изобретателя REST.

Хотя мне нравится ответ Джастина, я чувствую, что он более точно представляет фильтр, а не поиск. Что если я захочу узнать об автомобилях с названиями, которые начинаются с cam?

На мой взгляд, вы можете встроить его в способ управления определенными ресурсами:
/ cars / cam *

Или просто добавить его в фильтр:
/ cars / doors / 4 / name / cam * / colors / red, синий, зеленый

Лично я предпочитаю последнее, однако я ни в коем случае не эксперт по REST (впервые услышав об этом всего 2 или около того недели назад ...)

RESTful не рекомендует использовать глаголы в URL-адресах / cars / search, не успокаивая. Правильный способ фильтрации / поиска / разбивки на страницы вашего API - через параметры запроса. Однако могут быть случаи, когда вам приходится нарушать норму. Например, если вы осуществляете поиск по нескольким ресурсам, вам нужно использовать что-то вроде / search? Q = query

Вы можете перейти на страницу http://saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/, чтобы ознакомиться с лучшими методиками разработки API-интерфейсов RESTful.

Кроме того, я бы также предложил:

/cars/search/all{?color,model,year}
/cars/search/by-parameters{?color,model,year}
/cars/search/by-vendor{?vendor}

Здесь Searchрассматривается как дочерний ресурс Carsресурса.

Есть много хороших вариантов для вашего случая здесь. Тем не менее, вы должны рассмотреть возможность использования тела POST.

Строка запроса идеально подходит для вашего примера, но если у вас есть что-то более сложное, например, произвольный длинный список элементов или логические условия, вы можете определить публикацию как документ, который клиент отправляет через POST.

Это позволяет более гибкое описание поиска, а также позволяет избежать ограничения длины URL-адреса сервера.

Мой совет будет таким:

/garages
  Returns list of garages (think JSON array here)
/garages/yyy
  Returns specific garage
/garage/yyy/cars
  Returns list of cars in garage
/garages/cars
  Returns list of all cars in all garages (may not be practical of course)
/cars
  Returns list of all cars
/cars/xxx
  Returns specific car
/cars/colors
  Returns lists of all posible colors for cars
/cars/colors/red,blue,green
  Returns list of cars of the specific colors (yes commas are allowed :) )

Редактировать:

/cars/colors/red,blue,green/doors/2
  Returns list of all red,blue, and green cars with 2 doors.
/cars/type/hatchback,coupe/colors/red,blue,green/
  Same idea as the above but a lil more intuitive.
/cars/colors/red,blue,green/doors/two-door,four-door
  All cars that are red, blue, green and have either two or four doors.

Надеюсь, это дает вам идею. По сути, ваш Rest API должен быть легко обнаруживаем и должен позволять вам просматривать ваши данные. Еще одним преимуществом использования URL-адресов, а не строк запроса, является то, что вы можете воспользоваться преимуществами собственных механизмов кэширования, которые существуют на веб-сервере для трафика HTTP.

Вот ссылка на страницу, описывающую зло строк запросов в REST: http://web.archive.org/web/20070815111413/http://rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful

Я использовал кеш Google, потому что у меня не работала обычная страница, вот эта ссылка: http://rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful