Thanks for the link.
First I need to say that your example due to the use of "do"-prefixed URIs
has a string RPC smell, which according to Mr Fielding, is not HATEOAS, and
such is not REST. Just wanted to remember that we're providing not any http
based API, bust exactly a REST API. Seeing "do" in REST always gives me a
bad feeling regarding the future developments. But this is a different
story. Back to your question: I mentioned that because it makes my answer
more complex, as my proposal has to be able to do RPC then, too. Ok, I'll
try it:
You asked: "I may want to start machine A and stop machine B; so getting the
links to all the machines in the cluster is not enough."
In your propsal the client must know how to puzzle together the template and
ID from this information:
</cluster/machine/%7Bname%7D>; produces="application/json"; method="GET";
rel="item"
and
"name": "alpha".
If the client would be a human, what you force him to do is:
* Read the name of the machine from the list of machines from a HTML table.
* Manually type in, or select from a list, the name of the machine to stop
in a HTML form.
* Press STOP button to send HTML form.
Certainly a human can do that, but wouldn't it be smarter to have a
specialized link besides each machine? Like a stop sign in the same line,
directly besides a nice icon showing the machine's state? Clearly it would
be. So what would that special like look like? Well, in HTML it would be an
<a> tag containing the transition ("action") *and* the name of machine
within it's target href URI. As there are many machines, there would be many
such <a> tags. This points the way towards a RESTful solution without
templates:
The "Link:" header must contain one URI per machine plus transition
combination.
You might say: How shall a client know wich one to invoke then? Well, how
does a human know? The human just knows by guessing or reading. His attemps
are more an intuitive good guess (or a smart tool tip telling him in his
mother's tongue). But, as a machine can neither guess nor understand
tooltips, it just could pick one of two strategies: (a) It is explicitly
written to orchestrate this particular service, so it just knows the syntax
of the URI (I mean, if I write an eBay client I obviously know the API,
which contains the particular URI syntax). One doesn't need a template then
(you only need a template, if you *do not* know the syntax and want some
background magic to handle this). (b) Just as a human, it can do assumptions
and pick that link that provides a tooltip containing the needed information
(i. e. it parses the "title" attribute for the assumed action name and known
machine name -- if it is clever enough to understand how to read the machine
name from the document, it is clever enough to do so, too). Both strategies
are likely to fail and will not serve our needs better than your idea. But.
Your solution will fail in the real world, too, due to:
(a) Polymorhy: Maybe there are "machine" instances that need to have
differnent URIs! You would need to provide a different template, but how to?
(b) Binary content: Maybe the machine "name" is not (or not easily)
parseable from the content! How would your client software guess the machine
name to pass into the template?
Your solution will fail in both cases, while the following proposal (which
is the answer to your question) will not:
My proposal is using the "anchor" attribute to address the machine. That
way, the "cluster" document in the example can hold a list of all possible
actions for all contained "machines", and it is clear what each link is good
for. Even in case of polymorphic "machine" instances (having different names
for the same action as they are provided by a different peace of controller
software or are located on a different control server), and even with binary
content not containing the machine IDs in any easily parseable form, this
would work well, is unambiguous, easy to use, and contained in
<
http://www.w3.org/Protocols/9707-link-header.html>
http://www.w3.org/Protocols/9707-link-header.html. And, it would be just
correct, as the source of the link is not the cluster, but the machine: You
want to instruct the machine to shut down, you do not want to instruct the
cluster to shut of the machine.
But, actually, if I were you, I would provide a different model in fact to
solve your task: Not sending all the transition links for all the machines
inside of the cluster document, but let the cluster document contain only
the machines "self" URIs (so you only learn the list of machines in the
first step -- maybe you neither want to know the state nor want to shut down
a machine, so you don't really lose anything in the first step). If a link
is needed for a machine (since you then want to know the status or want to
shutdown one machine), I can request the machine's representation in a
second roundtrip and find it's transition links inside that document. This
imposes one more http request, but it provides self-controlled machines,
which in fact solves not only the templates problem, the polymorphy problem
and the binary content problem, but it is also more scalable as for lots of
machines you would only ask for as much state as you can see on the screen
(not requesting machines states you won't read ever), and it is much more
object oriented: If I want to shut down a machine, I press it's power
switch. I do not press a swith on a different device. :-)
Regards
Markus
From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Dienstag, 8. November 2011 20:09
To: jsr339-experts_at_jax-rs-spec.java.net
Subject: [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Re: Re: Improving
Hypermedia Support
On Nov 8, 2011, at 12:39 PM, Markus KARG wrote:
Can you please post the WIKI link again? Thanks.
Here it is:
http://java.net/projects/jax-rs-spec/pages/HypermediaExample
-- Santiago
From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Montag, 7. November 2011 19:11
To: jsr339-experts_at_jax-rs-spec.java.net
Subject: [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Re: Improving
Hypermedia Support
Hi Markus,
Could you apply this to the example we have on the wiki? In particular,
given a collection item Y, how can I get the link to Y? I may want to start
machine A and stop machine B; so getting the links to all the machines in
the cluster is not enough.
-- Santiago
On Nov 6, 2011, at 8:45 AM, Markus KARG wrote:
Santiago,
this way:
Link: <absolute-uri-A1>; rel="name-of-collection-A"
Link: <absolute-uri-A2>; rel="name-of-collection-A"
Link: <absolute-uri-B1>; rel="name-of-collection-B"
Link: <absolute-uri-B2>; rel="name-of-collection-B"
Here you have four absolute URIs. A1 and A2 are part of collection A, B1 and
B2 are part of collection B.
If the client wants to visit all resources references by collection B, it
would just have to invoke A1 and A2, identified via collection A.
An alternative way would be using the anchor attribute to identify the
resource as a fragment of the source resource (e. g.
anchor="#name-of-collection-A").
A third option would be a link-extension like "Link: <absolute-uri>;
collection="name-of-collection".
Where do you see a problem? No need for neither templates nor client side
application logic.
Regards
Markus
From: Santiago Pericas-Geertsen [mailto:Santiago.PericasGeertsen_at_oracle.com]
Sent: Dienstag, 1. November 2011 20:17
To: jsr339-experts_at_jax-rs-spec.java.net
Subject: [jsr339-experts] Re: [jax-rs-spec users] Re: Re: Improving
Hypermedia Support
* I do not understand the problem with the collection. Why not sending just
several URIs with the same relation in that case (one for each item of the
collection)?
As link headers? How would you know which one corresponds to which item in
the collection? There's no ordering for link headers.
-- Santiago