Re: Link Relations

On 09.11.2013, at 18:59, Philippe Marsteau <[email protected]> wrote:

> I see 2 distinct purposes of link relations: either to qualified a transition from one state to another of the resource, or to describe how two resources relate one to another.

These are really the same thing.  The client activating controls based on what it learned about resources.

> 
> This discussion I think focused on the latter. I am specifically curious of best practices for the former case, when a RESTful API aims at letting consumer work through a specific workflow (eg. buying a book online).

There is a common confusion (I think - at least it was a confusion for me for years) with regard to the idea that the server is prescribing a workflow which the client follows.

In a RESTful system, the server actually has no idea about the application (the workflow) that the client executes. It is the client that owns the state machine. It is just that the client is programmed not to blindly assume the availability of certain transitions but to make the best of the controls it receives along the way.

At some point, it must give up, obviously - or reach a steady state and wait for a human to make the next move based on the accumulated information in that steady state.

> 
> I thought the best practice was to let user land ton an entry point resource (eg collection of books) and then let user evolve in the workflow: first by affording user to initiate the workflow (eg. "rel=buy" which likely translates with GETing a "buy-a-book-form" resource, letting user discover which inputs are need to start the workflow). Then subsequently, each step in the workflow will afford user to confirm an order, select payment information, shipping details... Ultimately the server will confirm creation of an order resource (and maybe  provide a shipment resource allowing user to track shipping status or to cancel order, etc.)

It is still the hard-coded or configured decision tree that determines the application here.... it is just that hypermedia is the *engine* :-)

> 
> In such typical workflow scenario, is it a bad practice to expose rels as "actions" (thus verbs)?

That is always bad practice.

> I think of having server sending relevant actions on each step (as part of resource representations), letting user discover HTTP methods and target resource to interact with as a result of activating the hypermedia control (action).
> 
> In the example of AtomPub, we have a similar hypermedia control "edit" (verb)

Which is a naming mistake - that should have been 'source' or so. Meaning: 'edit' links points to the resource that is the 'master' - the one you mutate - as opposed to the member entry resources.

> to afford atom consumer a given feed entry can be edited. Which translate with a PUT to the target href (the target feed entry).

Or DELETE or PATCH or whatnot.

> 
> In other words, what is the best practice to express hypermedia actions in a RESTful way, to allow consumer to control the workflow while the server controls the affordances of the user (based on internal application state)?

Use link semantics (link rels, but also stuff like <html:img src=""/> or <atom:collection href="">) to tell the consumer what a target *is* to the context. Let the client decide the rest ... the server cannot know what the client is programmed to do anyhow. Instead of designing to prescribe application flow, design for max. re-usability.

HTH

Jan


> 
> Phil
> 
> Le 8 nov. 2013 à 02:58, Mike Kelly <[email protected]> a écrit :
> 
>>  
>> On Fri, Nov 8, 2013 at 1:31 AM, Jan Algermissen
>> <[email protected]> wrote:
>> > Hi Mike,
>> >
>> > On 08.11.2013, at 02:08, mike amundsen <[email protected]> wrote:
>> >
>> >>
>> >> not sure i understand the Q, but i'll offer this:
>> >>
>> >> rel="http://example.com/rels/publisher" describes the relationship between the source and the target.
>> >>
>> >
>> > I like to try to emphasize what the target is *to the source* with the goal that the application-level effect of the HTTP methods falls into place.
>> >
>> > This IMO helps a great deal with avoiding to layer specialized application protocols on top of HTTP (which already is the application protocol).
>> >
>> > IOW, it helps prevent redefinitions of the meaning of HTTP methods. POST means POST, it cannot mean 'publish the source resource'. DELETE means DELETE, it cannot mean 'unpublish the the source resource'.
>> >
>> 
>> Well, those methods have a general meaning within the uniform
>> interface of HTTP whose purpose is to add to the self-descriptiveness
>> of messages and, in doing so, to afford intermediation across the
>> system (e.g. web caching). The HTTP method definitions attribute
>> meaning designed for this purpose (e.g. establishing safety,
>> idempotency, cacheability, etc).
>> 
>> Provided the link relations are not in conflict with the HTTP
>> definitions, and are merely qualifying the details of methods within
>> the context of a given transition, then it is wrong to think about
>> that in terms of "redefinition". It's qualification.
>> 
>> In practice, it's much easier for consuming parties if your
>> documentation is specific by providing an explicit description of the
>> meaning and structure of the various requests possible over a given
>> link. Leaving your documentation so abstract that the reader is left
>> with the task of inferring every part of each possible request does
>> not seem like a very pragmatic approach for custom link relations (but
>> may be more appropriate for standardised link relations).
>> 
>> > If you find yourself in a situation that you absolutely must tell the client developer this, rephrase the hypermedia semantic (here: the link rel spec).
>> >
>> > There is nothing to say againts hints regarding the intended 'canonical' use case but I can always only be a hint. AtomPub is an example, where the spec tells us so much about the interactions between client and server that it looks like a protocol when it is actually only hints about a canonical application flow. Focussing on resource semantics would have been much nicer, IMHO.
>> >
>> > One simply cannot constrain HTTP servers that way and still have REST.
>> >
>> 
>> The importance of HTTP methods from a REST point of view is that they
>> create **some** visibility of the client server interactions, so that
>> the messages can be understood to _a certain extent_ by
>> intermediaries. Provided that visibility is not impacted (i.e. a link
>> rel's qualification of a method doesn't _conflict_ with HTTP's) then
>> how does this have any bearing on the "RESTfulness" of the
>> application?
>> 
>> Cheers,
>> M
>> 



------------------------------------

Yahoo Groups Links

<*> To visit your group on the web, go to:
    http://groups.yahoo.com/group/rest-discuss/

<*> Your email settings:
    Individual Email | Traditional

<*> To change settings online go to:
    http://groups.yahoo.com/group/rest-discuss/join
    (Yahoo! ID required)

<*> To change settings via email:
    [email protected] 
    [email protected]

<*> To unsubscribe from this group, send an email to:
    [email protected]

<*> Your use of Yahoo Groups is subject to:
    http://info.yahoo.com/legal/us/yahoo/utos/terms/