Query parameters create hyperlink templates.

So

    href="foo/bar/?baz=x"

is really a way for generating a set of hyperlinks that range over whatever domain x comes from and the client should feel free to plug in any valid value for x. You can even indicate the domain of x by returning a 405 in the case of an invalid value (although it would be nice to have a standard way of indicating the domain beforehand)

For instance, if there are 10 pages then x ranges over [1-10]. If the client request ?page = 11 then we'd return a 405 error indicating that the only valid values are [1-10].

I find URL templates smelly. Once you stick a place holder in the URL, it's no longer a valid URL - it's something that requires custom mangling before it can be passed along.

In your example, I need to know that the x is something that requires replacement. How is that fundamentally different from just putting in your documentation (and, in the 405 if not passed) "this resources takes query param baz" - which is not HATEOS?

Also, this doesn't cover the case of optional parameters. Specifying optionality in a template is horrible (something like "bar/?baz=x[&ogle=y]" to borrow the pattern from man pages), and specifying individual URLs for each combination of parameters is impractical for more than a few.

> I find URL templates smelly. Once you stick a place holder in the URL, it's no longer a valid URL - it's something that requires custom mangling before it can be passed along.

This is why a standard has been drafted for this particular problem, the mangling becomes standard and predictable rather than customized to each use case.

http://tools.ietf.org/html/draft-gregorio-uritemplate-08

It may smell, but clients that uses URL templates may still be RESTful. For this to work, 1.) the server must decorate the response with the proper resource type identifier, 2.) the client must be able to understand the resource type, and 3.) the resource type spec must specify how the clients should treat URL templates.

Web browsers are REST clients that understand the HTML resource type. They, too, can generate URLs. For example, in HTML, you can specify a URL template with the following code:

    <form action="foo/bar/" method="get">
      <input name="baz" type="text">
      <input type="submit" value="Submit" />
    </form>

Input tags with type="text" are, by default, optional. Newer HTML spec allows you to annotate input tags with the "required" attribute, which allows you to specify them as required.

You can define your custom resource type to do the same if you want:

    { "form": { "action": "foo/bar/",
                "method": "GET",
                "fields": [ { "name" : "baz" } ]
    }

You can make the above example a lot leaner by trimming out features you don't care about. It's all up to how you design the spec of your resource type.

According to Steve Klabnik, this can be accomplished via GET forms and using query templates: http://amundsen.com/media-types/collection/format/#query-tem...

An HTML form could be one way of doing this. As long as the API complies with the form it sends out.

However, getting a client to automatically understand this is a little harder.

You could approximate a form in JSON, which would be similar in structure to its HTML counterpart.

This is such a fundamental problem that I am surprised that there is not a definitive answer.

I think you should have a pagination resource that understands a resource and returns a paginated URL.

it would accept parameters. I think having a template requires the client to understand a format other than hypertext.

The HTML form tag; also expressed more directly as URL templates. The server provides the parameterized template, and the client fills in the params to access the resource.

There is actually a HTTP header (Range) that can be used for this. Works well in APIs but you can't do it with browsers, which is unfortunate.

Can you not set custom headers in browsers?

You can do it with AJAX requests, but not with links or regular forms (as far as I am aware... I'd love to hear otherwise)

Should a REST API ever be expose by a form or link?

The web is basically a REST API, no? (I'm being a bit facetious.)