Loading ...
Sorry, an error occurred while loading the content.

19554Re: [rest-discuss] Link Relations

Expand Messages
  • Philippe Marsteau
    Nov 9, 2013
    • 0 Attachment
      Appreciate the feedback and experience sharing.

      So reusing my use case if buying a book, what rels would define from the root book collection resource? (assuming the application is designed to let customers buy books).

      How do I let the consumer discover a book listed in the collection can now be "bought"?

      I believe there are cases where the server dictates the steps before a book order can be placed: server decides shipment info is ended or payment info is needed. I mean the book listed in store does not have a model relationship "orders" linking to it, does it? 

      You cannot create an order until user goes through a server defined list of steps. Furthermore, the steps could be different per user (eg one who already stored his payment/shipping on file for future orders).

      While I completely understand it is the consumer who activates the hypermedia controls, and thus the workflow progress depends on the user, I need a way to let consumer discover through hypermedia controls "what" can be done at each step of the application business workflow (here: what info must be entered to complete the book order process?), based on user permissions or internal application state...

      Your further guidance is appreciated!

      Le 9 nov. 2013 à 14:25, mike amundsen <mamund@...> a écrit :

      I will say that i've gone both routes (using rels to indicate relationships and using rels to indicate actions) and am not settled on either.

      the "rel" community def. wants to see this attribute used to indicate relationships. reviews of  recently registered values at the IANA show this.

      however, i can see the appeal and value of having action indicators on hypermedia controls; esp. in cases where machines are doing the work of selecting controls to activate. in this case it seems efficient to reduce the "decision distance" of 1) find the control that has an id of the desired target then, 2) look at the control to see what protocol action is available to 1) find the control that has the id of the desired action of the target. But this is, in the long run, a false efficiency. It _assumes_ the client code already "knows" things (action and target are coupled) and constrains the possible options for the client ("you can only do a single action for this control, want to do some other action? sorry, no control for that here, move along").

      in the big picture, i've found keeping target identifiers (collection, storage, document, person) decoupled from action (share, modify, copy, move, approve, cancel) is a big win. while it adds some indirection/complexity to the representation (both at design-time and run-time) this pattern also adds more options and increases the independence of the client application. including allowing clients to (in some cases) create new successful workflows that the server didn't map out even though it is completely allowed by the state machine.

      FWIW, if you want to continue to constrain clients to only following strict server pre-defined paths, you can still do that while sticking to the "rel is for relationships" pattern.

      Cheers.





      On Sat, Nov 9, 2013 at 12:59 PM, Philippe Marsteau <marsteau@...> 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.

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

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

      In such typical workflow scenario, is it a bad practice to expose rels as "actions" (thus verbs)? 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) to afford atom consumer a given feed entry can be edited. Which translate with a PUT to the target href (the target feed entry).

      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)?

      Phil

      Le 8 nov. 2013 à 02:58, Mike Kelly <mikekelly321@...> a écrit :

       

      On Fri, Nov 8, 2013 at 1:31 AM, Jan Algermissen
      <jan.algermissen@...> wrote:
      > Hi Mike,
      >
      > On 08.11.2013, at 02:08, mike amundsen <mamund@...> 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


    • Show all 25 messages in this topic