[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: [rest-practices] Links for actions





David Lutterkort wrote:
On Fri, 2010-05-07 at 08:45 +0100, Eoghan Glynn wrote:
On Thu, 2010-05-06 at 16:46 -0700, David Lutterkort wrote:
One more issue from Deltacloud Core: right now, when a client gets the
details about an instance, we indicate the possible actions on that
instance like this:

        <actions>
          <link href="/api/instances/inst1/reboot" rel="reboot"/>
          <link href="/api/instances/inst1/stop" rel="stop"/>
          <link href="/api/instances/inst1" rel="destroy"/>
        </actions>
The above leaves the client guessing what method to use on the actions,
and contains a little trap: for almost all actions, the method to use is
POST, but for destroy, the client should use the DELETE method, since
they are deleting the server side instance.

You could argue that this issue is caused by using URL's that do not
represent resources; but then I don't know a better way to indicate
actions.

My favored way out of this is to add the method the client should use to
the <link/> tag, e.g.

        <link href="/api/instances/inst1" rel="destroy" method="post"/>

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.


+1. There should be no special meaning assigned to error codes. The client should already be aware, through the HTTP specification, what error codes it needs to handle and how. If you need more fine grain error messages, then IMO, enclose a media type that tells the client what to do.

What I've encountered so far, is that if you rely on the HTTP specification, things get simpler and change is easier to introduce. The key always is to have the client react to what the server is telling it what to do.


--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]