[rest-practices] Links for actions

[Itamar Heim]

> From: rest-practices-bounces at redhat.com [mailto:rest-practices-
> bounces at redhat.com] On Behalf Of David Lutterkort
...
> > Just playing devil's advocate for a moment, but aren't we already
> > implying quite an amount of semantic and structural information in
> the
> > rel label?
> 
> Yes, that's true .. and yet, the method is what tripped at least one
> client up. The instance actions in the deltacloud API are otherwise
> very
> uniform: they take no parameters and no request body, and return the
> instance. Adding a method in this specific case allows client code to
> remove one special case.
> 
> > But it would probably be over the top to try to encode all that
> > information explicitly in the link element, e.g.
> >
> > <link rel="attach" href="/storagedomains/XXX/attach"
> > type="application/vnd.redhat.rhevm-api.Action+{xml|json}"
> > errorStatus="400,401,403,409,412" method="POST" />
> >
> > as most of this information can be implicit, or captured in the
> > documentation etc.
> 
> Agreed .. encoding all of that would be overkill. The confusion with
> actions and links really stems from the fact that the URL's mentioned
> in
> the link are not resources in the usual REST+HTTP sense, i.e., they
> only
> respond to one specific method, and you can't even do a GET on them.
> 
> > If we were to encode anything explicitly, I'm thinking the expected
> > fine-grained media type must be more useful information, as the verb
> is
> > usually POST and in any case if the client gets it wrong we can prod
> it
> > into recovering gracefully via a 405 "Method Not Allowed" response
> with
> > an "Allow: DELETE" header for example.
> 
> I wonder how many clients will implement this kind of error recovery
> properly ;)
[IH] I agree with David. Developers should be able to use the API easily
(hopefully via IDE's with intellisense actually). Forcing the developer to
go and read the documentation for each API (hoping the documentation would
actually be up to date) is not very friendly.