5 ms·

What is the HATEOS compliant way of accepting parameters? E.g. for the pagination example, you might want to let the consumer specify number of entries pr. page

What is the HATEOS compliant way of accepting parameters? E.g. for the pagination example, you might want to let the consumer specify number of entries pr. page, or you might want to accept a search-term or limit by period.

scott_w 15y ago
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.
- sopooneo 15y ago
  This is such a fundamental problem that I am surprised that there is not a definitive answer.
justinludwig 15y ago
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.
noblethrasher 15y ago
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].
- mseebach 15y ago
  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.
  - grncdr 15y ago
    > 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 http://tools.ietf.org/html/draft-gregorio-uritemplate-08
    - Kiall 15y ago
      Ooo - Very interesting, I've been looking for something like this. I even wrote my own version of this a while back, and scrapped it due to the complexity. A standard would allow for the complexity to be wrapped away in a library :)
  - buddydvd 15y ago
    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.
- deleted 15y ago
  [deleted]
mahmoudimus 15y ago
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.
- deleted 15y ago
  [deleted]
gotmayonase 15y ago
According to Steve Klabnik, this can be accomplished via GET forms and using query templates: http://amundsen.com/media-types/collection/format/#query-templates http://amundsen.com/media-types/collection/format/#query-tem...
bodhi 15y ago
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.
- alexchamberlain 15y ago
  Can you not set custom headers in browsers?
  - bodhi 15y ago
    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)
    - alexchamberlain 15y ago
      Should a REST API ever be expose by a form or link?
      - bodhi 15y ago
        The web is basically a REST API, no? (I'm being a bit facetious.)

scott_w 15y ago

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.

sopooneo 15y ago
This is such a fundamental problem that I am surprised that there is not a definitive answer.

justinludwig 15y ago

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.

noblethrasher 15y ago

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

mseebach 15y ago
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.
- grncdr 15y ago
  > 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 http://tools.ietf.org/html/draft-gregorio-uritemplate-08
  - Kiall 15y ago
    Ooo - Very interesting, I've been looking for something like this. I even wrote my own version of this a while back, and scrapped it due to the complexity. A standard would allow for the complexity to be wrapped away in a library :)
- buddydvd 15y ago
  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.
deleted 15y ago
[deleted]

mahmoudimus 15y ago

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.

deleted 15y ago
[deleted]

gotmayonase 15y ago

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

bodhi 15y ago

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.

alexchamberlain 15y ago
Can you not set custom headers in browsers?
- bodhi 15y ago
  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)
  - alexchamberlain 15y ago
    Should a REST API ever be expose by a form or link?
    - bodhi 15y ago
      The web is basically a REST API, no? (I'm being a bit facetious.)