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

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

GET/users

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

GET/users? surname = Harvey & maxResults = 25

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

Заранее благодарю вас!

Ответы

Ответ 1

Используя синтаксис, описанный в текущем черновике

Ответ 2

Другой вариант - использовать форму 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-адрес и может быть аннотирована с любой дополнительной документацией, которую вы хотите разместить там.

Ответ 3

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

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

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

  • Откройте подресурс, представляющий поиск пользователей, /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.

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