Как я могу использовать HATEOAS и параметры запроса для поиска RESTful? - PullRequest
Новая
       11

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

33 голосов
/ 16 мая 2011

Я хотел бы создать URI поиска RESTful, используя параметры запроса.Например, этот URI возвращает список всех пользователей:

GET / users

и первых 25 пользователей с фамилией "Harvey":

GET / users? Фамилия = Harvey & maxResults = 25

Как я могу использовать гипермедиа для описания того, какие параметры запроса разрешены ресурсом "/ users"?Я заметил, что новый Google Tasks API просто документирует все параметры запроса в справочном руководстве.Я задокументирую список, но я бы хотел сделать это и с HATEOAS.

Заранее спасибо!

Ответы [ 3 ]

21 голосов
/ 16 мая 2011

Используя синтаксис, описанный в текущем проекте спецификации шаблона URI , вы должны сделать: 

/users{?surname,maxresults}
6 голосов
/ 17 мая 2011

Другой вариант - использовать HTML-форму: 

<form method="get" action="/users">
   <label for="surname">Surname: </label>
     <input type="text" name="surname"/>
   <label for="maxresults">Max Results: </label>
     <input type="text" name="maxresults" value="25"/> <!-- default is 25 -->
   <input type="submit" name="submitbutton" value="submit"/>
</form>

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

1 голос
/ 21 июня 2015

Я не эксперт по REST, но позвольте мне добавить 2 ¢:

В человеческом Интернете формы HTML часто используются для построения URI для представления результатов поиска.Проблема в том, что программируемый веб не имеет форм.Но вы можете легко определить что-то аналогичное себе, например:

  1. Определите тип носителя для описаний поиска, скажем, application/prs.example.searchdescription+json (но обратите внимание на PS в конце этогоответ);

  2. Предоставить подресурс, представляющий поиск пользователей, /users/search.

Второй шаг будет достигнутссылка на этот подресурс откуда-то еще.Например, скажем, клиент запросил GET /users.Он может получить что-то вроде этого: 

{ _links: [ …, { rel: "search", href: "/users/search" }, …] }

Клиент может перейти по этой ссылке и POST спецификация поиска для этого ресурса URI, например: 

POST /users/search
…
Content-Type: application/prs.example.search-definition+json
…

{ criteria: { surname: "Harvey" }, maxResults: 25 }

Здесь, criteria содержит (частичное) представление объектов, которые будут найдены.Это может быть сделано в произвольно сложном описании.

На запрос, как описано выше, сервер может затем ответить кодом состояния 200 OK и, в теле объекта, ссылкой на ресурс, представляющий результаты дляотправленный поиск: 

{ _links: [ { rel: "results", href: "/users?surname=Harvey&maxResults=25" } ] }

Затем клиент может перейти к URI с отношением results, чтобы получить результаты поиска, даже не собирая сам URI.

PS : Когда я изначально писал это, я еще не осознавал, что определение новых типов носителей все время может стать проблематичным. Марк Ноттингем писал о «распространении медиа-типов» и о том, как с ним бороться , используя profile связь .

...