How can I use HATEOAS and Query Parameters for RESTful search?

Question

I would like to design a RESTful search URI using query parameters. For example, this URI returns a list of all users:

GET /users

And the first 25 users with the last name "Harvey":

GET /users?surname=Harvey&maxResults=25

How can I use hypermedia to describe what query parameters are allowed by the "/users" resource? I noticed that the new Google Tasks API just documents all the query parameters in the reference guide. I will document the list, but I would like to do it with HATEOAS too.

Thank you in advance!

Answer 1

Using the syntax described in the current draft of the URI template spec you would do:

/users{?surname,maxresults} 

Answer 2

The other option is to use an html form:

<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> 

A form like this fully documents the available options and any defaults, it creates the specified URL and can be annotated with any further documentation that you care to put there.