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

Link Relations

Expand Messages
  • Charles Reese
    Hi all, I m looking at HAL and Collection+JSON for an API I m building. I was wondering if there are any community norms for constructing link relations. Here
    Message 1 of 25 , Nov 5, 2013
    • 0 Attachment
      Hi all,

      I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.

      Here is what I'm considering:

      Option 1:

      /rels/playlists
      /rels/playlist
      /rels/playlist/insert-song
      /rels/playlist/remove-song

      Option 2:

      /rels/playlist
      /rels/playlist/create
      /rels/playlist/edit
      /rels/playlist/delete
      /rels/playlist/insert-song
      /rels/playlist/remove-song

      Option 3:

      list
      create
      edit
      delete
      insert-song
      remove-song

      The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.

      Which of these is preferred? Are there better options?

      Charles
    • Alexander Johannesen
      Hiya, /rels/playlist/insert-song ... ... /rels/playlist/create ... Hmm, you re aware that all these URIs are evil, right? :) Here s what I would do ; /playlist
      Message 2 of 25 , Nov 5, 2013
      • 0 Attachment
        Hiya,

        /rels/playlist/insert-song
        /rels/playlist/remove-song
        ...
         /rels/playlist/create
        /rels/playlist/edit
        /rels/playlist/delete
        /rels/playlist/insert-song
        /rels/playlist/remove-song
        ... 
        create
        edit
        delete
        insert-song
        remove-song

        Hmm, you're aware that all these URIs are evil, right? :)

        Here's what I would do ;

        /playlist
        /playlist/{$list_name}
        /playlist/{$list_name}/{$song_id}

        The rest is GET, PUT, POST and DELETE on those three (well, one static and two dynamic) URIs. Remember to think in terms of resources (so, the songs and the lists themselves) for URIs, and use REST for interaction on those resources.


        Kind regards,

        Alex
      • Erik Mogensen
        6. nov. 2013 06:39 skrev Alexander Johannesen
        Message 3 of 25 , Nov 5, 2013
        • 0 Attachment


          6. nov. 2013 06:39 skrev "Alexander Johannesen" <alexander.johannesen@...> følgende:

          >
          > Hmm, you're aware that all these URIs are evil, right? :)
          >
          > Here's what I would do ;

          You probably missed the part where the OP said he was discussing link relations, not resource URIs. :-)

          I am not aware of any concencus; general URI rules apply, such as Cool URIs don't change. I would look in the link relation registry for inspiration (and reuse where appropriate).
          --
          -mogsie-

        • Alexander Johannesen
          Hi, And oops! But through the egg on my face, I mutter, there s *some* implications, but not really REST ... while coughing ironically into a jug of coffee.
          Message 4 of 25 , Nov 5, 2013
          • 0 Attachment
            Hi,

            And oops! But through the egg on my face, I mutter, "there's *some*
            implications, but not really REST ..." while coughing ironically into
            a jug of coffee. More coffee!


            Alex

            On Wed, Nov 6, 2013 at 5:27 PM, Erik Mogensen <erik@...> wrote:
            >
            > 6. nov. 2013 06:39 skrev "Alexander Johannesen"
            > <alexander.johannesen@...> følgende:
            >
            >>
            >> Hmm, you're aware that all these URIs are evil, right? :)
            >>
            >> Here's what I would do ;
            >
            > You probably missed the part where the OP said he was discussing link
            > relations, not resource URIs. :-)
            >
            > I am not aware of any concencus; general URI rules apply, such as Cool URIs
            > don't change. I would look in the link relation registry for inspiration
            > (and reuse where appropriate).
            > --
            > -mogsie-



            --
            Project Wrangler, SOA, Information Alchemist, UX, RESTafarian, Topic Maps
            http://shelter.nu/blog | google.com/+AlexanderJohannesen |
            http://xsiteable.org
            http://www.linkedin.com/in/shelterit
          • mike amundsen
            Charles: First, if you use single strings ( edit , etc.) be sure they are registered Link Relation Values. Here s a good list of references: - IANA [1] -
            Message 5 of 25 , Nov 6, 2013
            • 0 Attachment
              Charles:

              First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
              - IANA [1]
              - microformats [2]
              - Dublin Core [3]

              When you *do* use them, be sure to mention in your documentation which are used and where they are registered.

              Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.

              Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:

              insert-song -> song (w/ HTTP.POST)
              remove-song -> song (w/ HTTP.DELETE)

              Cheers.






              On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:


              Hi all,

              I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.

              Here is what I'm considering:

              Option 1:

              /rels/playlists
              /rels/playlist
              /rels/playlist/insert-song
              /rels/playlist/remove-song

              Option 2:

              /rels/playlist
              /rels/playlist/create
              /rels/playlist/edit
              /rels/playlist/delete
              /rels/playlist/insert-song
              /rels/playlist/remove-song

              Option 3:

              list
              create
              edit
              delete
              insert-song
              remove-song

              The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.

              Which of these is preferred? Are there better options?

              Charles



            • Charles Reese
              Hi Mike, Thank you so much! I m still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a
              Message 6 of 25 , Nov 7, 2013
              • 0 Attachment
                Hi Mike,

                Thank you so much!

                I'm still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a playlist, it defaults to 'private'. I want to turn it public. I could use a link rel like this:

                /rel/playlist/publish

                But again, I'm not using the method as the "verb". How would you handle this?

                Cheers,
                Charles


                On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <mamund@...> wrote:
                Charles:

                First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
                - IANA [1]
                - microformats [2]
                - Dublin Core [3]

                When you *do* use them, be sure to mention in your documentation which are used and where they are registered.

                Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.

                Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:

                insert-song -> song (w/ HTTP.POST)
                remove-song -> song (w/ HTTP.DELETE)

                Cheers.






                On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:


                Hi all,

                I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.

                Here is what I'm considering:

                Option 1:

                /rels/playlists
                /rels/playlist
                /rels/playlist/insert-song
                /rels/playlist/remove-song

                Option 2:

                /rels/playlist
                /rels/playlist/create
                /rels/playlist/edit
                /rels/playlist/delete
                /rels/playlist/insert-song
                /rels/playlist/remove-song

                Option 3:

                list
                create
                edit
                delete
                insert-song
                remove-song

                The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.

                Which of these is preferred? Are there better options?

                Charles




              • mike amundsen
                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. now you
                Message 7 of 25 , Nov 7, 2013
                • 0 Attachment
                  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.

                  now you can describe (or write docs in human form, etc.) how to exploit the relationship using protocols:
                  HTTP.POST === publish the source resource
                  HTTP.DELETE === unpublish the the source resource
                  HTTP.GET === get publishing metadata/status about the source resource
                  or whatever (i made up actions since i don't know your domain model)

                  hope this helps.




                  On Thu, Nov 7, 2013 at 6:10 PM, Charles Reese <charles.reese@...> wrote:
                  Hi Mike,

                  Thank you so much!

                  I'm still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a playlist, it defaults to 'private'. I want to turn it public. I could use a link rel like this:

                  /rel/playlist/publish

                  But again, I'm not using the method as the "verb". How would you handle this?

                  Cheers,
                  Charles


                  On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <mamund@...> wrote:
                  Charles:

                  First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
                  - IANA [1]
                  - microformats [2]
                  - Dublin Core [3]

                  When you *do* use them, be sure to mention in your documentation which are used and where they are registered.

                  Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.

                  Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:

                  insert-song -> song (w/ HTTP.POST)
                  remove-song -> song (w/ HTTP.DELETE)

                  Cheers.






                  On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:


                  Hi all,

                  I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.

                  Here is what I'm considering:

                  Option 1:

                  /rels/playlists
                  /rels/playlist
                  /rels/playlist/insert-song
                  /rels/playlist/remove-song

                  Option 2:

                  /rels/playlist
                  /rels/playlist/create
                  /rels/playlist/edit
                  /rels/playlist/delete
                  /rels/playlist/insert-song
                  /rels/playlist/remove-song

                  Option 3:

                  list
                  create
                  edit
                  delete
                  insert-song
                  remove-song

                  The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.

                  Which of these is preferred? Are there better options?

                  Charles





                • Jan Algermissen
                  Hi Mike, ... 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
                  Message 8 of 25 , Nov 7, 2013
                  • 0 Attachment
                    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'.

                    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.

                    (No to imply, BTW, that Mike did any such thing with his reply - I just felt like adding this before going to sleep :-)

                    Jan



                    > now you can describe (or write docs in human form, etc.) how to exploit the relationship using protocols:
                    > HTTP.POST === publish the source resource
                    > HTTP.DELETE === unpublish the the source resource
                    > HTTP.GET === get publishing metadata/status about the source resource
                    > or whatever (i made up actions since i don't know your domain model)
                    >
                    > hope this helps.
                    >
                    >
                    > mamund
                    > +1.859.757.1449
                    > skype: mca.amundsen
                    > http://amundsen.com/blog/
                    > http://twitter.com/mamund
                    > https://github.com/mamund
                    > http://www.linkedin.com/in/mamund
                    >
                    >
                    > On Thu, Nov 7, 2013 at 6:10 PM, Charles Reese <charles.reese@...> wrote:
                    > Hi Mike,
                    >
                    > Thank you so much!
                    >
                    > I'm still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a playlist, it defaults to 'private'. I want to turn it public. I could use a link rel like this:
                    >
                    > /rel/playlist/publish
                    >
                    > But again, I'm not using the method as the "verb". How would you handle this?
                    >
                    > Cheers,
                    > Charles
                    >
                    >
                    > On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <mamund@...> wrote:
                    > Charles:
                    >
                    > First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
                    > - IANA [1]
                    > - microformats [2]
                    > - Dublin Core [3]
                    >
                    > When you *do* use them, be sure to mention in your documentation which are used and where they are registered.
                    >
                    > Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.
                    >
                    > Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:
                    >
                    > insert-song -> song (w/ HTTP.POST)
                    > remove-song -> song (w/ HTTP.DELETE)
                    >
                    > Cheers.
                    >
                    > [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
                    > [2] http://microformats.org/wiki/existing-rel-values
                    > [3] http://dublincore.org/documents/dcmi-terms/
                    > [4] http://tools.ietf.org/html/rfc5988
                    >
                    >
                    >
                    > mamund
                    > +1.859.757.1449
                    > skype: mca.amundsen
                    > http://amundsen.com/blog/
                    > http://twitter.com/mamund
                    > https://github.com/mamund
                    > http://www.linkedin.com/in/mamund
                    >
                    >
                    > On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:
                    >
                    >
                    > Hi all,
                    >
                    > I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.
                    >
                    > Here is what I'm considering:
                    >
                    > Option 1:
                    >
                    > /rels/playlists
                    > /rels/playlist
                    > /rels/playlist/insert-song
                    > /rels/playlist/remove-song
                    >
                    > Option 2:
                    >
                    > /rels/playlist
                    > /rels/playlist/create
                    > /rels/playlist/edit
                    > /rels/playlist/delete
                    > /rels/playlist/insert-song
                    > /rels/playlist/remove-song
                    >
                    > Option 3:
                    >
                    > list
                    > create
                    > edit
                    > delete
                    > insert-song
                    > remove-song
                    >
                    > The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.
                    >
                    > Which of these is preferred? Are there better options?
                    >
                    > Charles
                    >
                    >
                    >
                    >
                    >
                    >
                    >
                  • Mike Kelly
                    On Fri, Nov 8, 2013 at 1:31 AM, Jan Algermissen ... Well, those methods have a general meaning within the uniform interface of HTTP whose purpose is to add to
                    Message 9 of 25 , Nov 7, 2013
                    • 0 Attachment
                      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
                    • Jan Algermissen
                      ... These are really the same thing. The client activating controls based on what it learned about resources. ... There is a common confusion (I think - at
                      Message 10 of 25 , Nov 9, 2013
                      • 0 Attachment
                        On 09.11.2013, at 18:59, 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.

                        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 <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
                        >>
                      • mike amundsen
                        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
                        Message 11 of 25 , Nov 9, 2013
                        • 0 Attachment
                          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


                        • Philippe Marsteau
                          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?
                          Message 12 of 25 , 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


                          • mike amundsen
                            FWIW, you re getting in to design space here - and that s based on context and preference. nothing right/wrong here so there are lots of options. first, i
                            Message 13 of 25 , Nov 9, 2013
                            • 0 Attachment
                              FWIW, you're getting in to "design" space here - and that's based on context and preference. nothing right/wrong here so there are lots of options.

                              first, i usually indicate state properties of a resource using data elements in the representation, not transition elements:

                              <book>
                                <in-stock value="true" />
                                <link href="..." rel="http://example.com/rels/shopping-cart" />
                              </book>

                              again, instructions on the link identified as the shopping cart might look like this:
                              - HTTP.GET returns the state of the shopping cart
                              - HTTP.POST adds the current book to the shopping cart
                              - HTTP.DELETE clears all items from the shopping cart
                              and so on...

                              now clients (humans) can see that the "state" of the book is "in-stock" and then decide to take an appropriate action.


                              as for "I believe there are cases where the server dictates the steps before"...

                              yes, the server may have rules about what "state" server-side resources need to have before a task can be executed. This can be viewed as dictating that "state" of things on the server, not dictating the order in which things happen on the client. This POV is close to the way programmers had to (re)learn to design user interfaces with teh advent of the pointer device (mouse). Suddenly, users could not be "led" from input to input in a certain order. Users had be power (and audacity) to click around on the screen, enter things in various order and so on. It was bedlam (grin)!

                              eventually, we learned to build UIs that used things like progressive disclosure, disabling items until certain "state" in the UI is achieved, etc.

                              we need to do that same for hypermedia services on the web. 

                              hope this helps.




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



                            • Philippe Marsteau
                              Interesting... Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not
                              Message 14 of 25 , Nov 9, 2013
                              • 0 Attachment
                                Interesting... 

                                Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...

                                Also where in this context fit the concept of forms, allowing user to fill in some parameters, before user can actually add the book in the shipping cart (eg, number of books to add)? Would the representation include a link to the form (instead of to the shopping cart directly), and its doc states only GET is allowed? The idea is to let user discover which attributes are need as input before a PUT (or POST or PATCH) can be called on the shopping cart... Instead of having client to hard code editable input fields to be requested to user ("knowing" the media type or profile of the shopping cart resource).

                                Thanks again, it helps.

                                Phil

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

                                FWIW, you're getting in to "design" space here - and that's based on context and preference. nothing right/wrong here so there are lots of options.

                                first, i usually indicate state properties of a resource using data elements in the representation, not transition elements:

                                <book>
                                  <in-stock value="true" />
                                  <link href="..." rel="http://example.com/rels/shopping-cart" />
                                </book>

                                again, instructions on the link identified as the shopping cart might look like this:
                                - HTTP.GET returns the state of the shopping cart
                                - HTTP.POST adds the current book to the shopping cart
                                - HTTP.DELETE clears all items from the shopping cart
                                and so on...

                                now clients (humans) can see that the "state" of the book is "in-stock" and then decide to take an appropriate action.


                                as for "I believe there are cases where the server dictates the steps before"...

                                yes, the server may have rules about what "state" server-side resources need to have before a task can be executed. This can be viewed as dictating that "state" of things on the server, not dictating the order in which things happen on the client. This POV is close to the way programmers had to (re)learn to design user interfaces with teh advent of the pointer device (mouse). Suddenly, users could not be "led" from input to input in a certain order. Users had be power (and audacity) to click around on the screen, enter things in various order and so on. It was bedlam (grin)!

                                eventually, we learned to build UIs that used things like progressive disclosure, disabling items until certain "state" in the UI is achieved, etc.

                                we need to do that same for hypermedia services on the web. 

                                hope this helps.




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



                              • mike amundsen
                                Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg
                                Message 15 of 25 , Nov 9, 2013
                                • 0 Attachment
                                  <snip>
                                  Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...
                                  </snip>

                                  If you wish to communicate this level of detail to clients (not at all a bad thing) often people think of these as _actions_ instead of states and just communicate the possible action:
                                  rel="clear"
                                  rel="add-book"
                                  and so forth.

                                  I try to steer clear of that whenever possible (as a design goal) and express these things as "states" on the server that need to be communicated to the client. for example (just making this up here...):
                                  - "clear" (the resource can be cleared or removed)
                                  - "edit" (the resource can be appended-to or child records can be added)
                                  and so forth.

                                  this means representations can look like this:
                                  <shopping-cart>
                                    <link href="..." rel="collection http://example.com/rels/shopping-cart" state="read clear" />
                                    <items count="9">
                                      <item href="..." rel="item http://example.com/rels/book" state="read clear">
                                        ...
                                      </item>
                                      ...
                                    </items>
                                  </shopping-cart>

                                  or you can use a much more explicit design:
                                  <shopping-cart>
                                    <clear href="..." rel="collection http://example.com/rels/shopping-cart" />
                                    <read href="..." rel="collection http://example.com/rels/shopping-cart" />
                                    <items count="9">
                                      <item>
                                        <clear href="..." rel="item http://example.com/rels/book" />
                                        <read href="..." rel="item http://example.com/rels/book" />
                                        ...
                                      </item>
                                      ...
                                    </items>
                                  </shopping-cart>

                                  These are just two possibilities. Note that i didn't include a protocol method in these designs, but that would be possible, too. an explicit example (one that might support more than one protocol) might look like this:
                                  <shopping-cart>
                                    <clear href="..." rel="collection http://example.com/rels/shopping-cart" method="HTTP.DELETE"/>
                                    <read href="..." rel="collection http://example.com/rels/shopping-cart" method="HTTP.GET"/>
                                    <items count="9">
                                      ...
                                    </items>
                                  </shopping-cart>

                                  Again, this is design so there are many possibilities.

                                  <snip>
                                  Also where in this context fit the concept of forms, allowing user to fill in some parameters...
                                  </snip>

                                  yes, i use forms quite often. this is about what state needs to be transferred from the client to the server (usually we only think about transferring state from server to client!). I might have a server that requires additional data in order to add an item to a cart:

                                    <data name="quantity" value="1" />
                                    <date name="stockid" value="q1w2e3" />
                                    <date name="required-delivery-date" value="2013-12-24" />
                                  </link>
                                  and so forth.

                                  I am in the habit of including forms in responses[0]. However, some folks prefer to only include links to forms and keep the forms as stand-alone resources[1]. Still others think it best not to include this information at all and keep that information as part of the documentation[2]

                                  Again, these are design decisions you can make on your own when creating your own message format (media type) or one that you can use to guide which of the existing registered types will best fit your needs/aesthetics.

                                  Cheers.







                                  On Sat, Nov 9, 2013 at 5:46 PM, Philippe Marsteau <marsteau@...> wrote:
                                  Interesting... 

                                  Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...

                                  Also where in this context fit the concept of forms, allowing user to fill in some parameters, before user can actually add the book in the shipping cart (eg, number of books to add)? Would the representation include a link to the form (instead of to the shopping cart directly), and its doc states only GET is allowed? The idea is to let user discover which attributes are need as input before a PUT (or POST or PATCH) can be called on the shopping cart... Instead of having client to hard code editable input fields to be requested to user ("knowing" the media type or profile of the shopping cart resource).

                                  Thanks again, it helps.

                                  Phil

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

                                  FWIW, you're getting in to "design" space here - and that's based on context and preference. nothing right/wrong here so there are lots of options.

                                  first, i usually indicate state properties of a resource using data elements in the representation, not transition elements:

                                  <book>
                                    <in-stock value="true" />
                                    <link href="..." rel="http://example.com/rels/shopping-cart" />
                                  </book>

                                  again, instructions on the link identified as the shopping cart might look like this:
                                  - HTTP.GET returns the state of the shopping cart
                                  - HTTP.POST adds the current book to the shopping cart
                                  - HTTP.DELETE clears all items from the shopping cart
                                  and so on...

                                  now clients (humans) can see that the "state" of the book is "in-stock" and then decide to take an appropriate action.


                                  as for "I believe there are cases where the server dictates the steps before"...

                                  yes, the server may have rules about what "state" server-side resources need to have before a task can be executed. This can be viewed as dictating that "state" of things on the server, not dictating the order in which things happen on the client. This POV is close to the way programmers had to (re)learn to design user interfaces with teh advent of the pointer device (mouse). Suddenly, users could not be "led" from input to input in a certain order. Users had be power (and audacity) to click around on the screen, enter things in various order and so on. It was bedlam (grin)!

                                  eventually, we learned to build UIs that used things like progressive disclosure, disabling items until certain "state" in the UI is achieved, etc.

                                  we need to do that same for hypermedia services on the web. 

                                  hope this helps.




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




                                • Philippe Marsteau
                                  Thank you Mike. That clarifies a lot. I think I misunderstood link relationships vs. capabilities/states. Your proposed approaches help me see how to better
                                  Message 16 of 25 , Nov 9, 2013
                                  • 0 Attachment
                                    Thank you Mike. That clarifies a lot. 

                                    I think I misunderstood link relationships vs. capabilities/states. Your proposed approaches help me see how to better design this. 

                                    A key requirement for me is to reduce as much as possible coupling, therefore I try to design resources as generically as possible (a list of simple attributes and a list of relationships/states) with the goal to allow for maximum evolvability of the API - given the mostly UI-driven interactions against the API. 

                                    Basically, I try to map the web pages one would interact with from a browser, but stripping out the UI elements (using generic JSON like format).

                                    By keeping the media type as low entry barrier (simple) as possible, assuming client will mostly render the data in its preferred technology, adding attributes or actions becomes highly dynamic without requiring consumer to "uptake" changes: attributes appear dynamically in UI front end and new interactions (think of "more actions" drop box) becomes added dynamically as well. I think your CJ media type is pretty generic too, so maybe this idea/goal is familiar to you...

                                    I also understand this might not fit for system to system type of interactions (scripted/automated integrations) and my goal might be too idealistic. Have you seen such type of REST APIs? Am I heading in the right direction?

                                    What about the others experience with forms resources vs strongly typed links?

                                    Phil

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

                                    <snip>
                                    Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...
                                    </snip>

                                    If you wish to communicate this level of detail to clients (not at all a bad thing) often people think of these as _actions_ instead of states and just communicate the possible action:
                                    rel="clear"
                                    rel="add-book"
                                    and so forth.

                                    I try to steer clear of that whenever possible (as a design goal) and express these things as "states" on the server that need to be communicated to the client. for example (just making this up here...):
                                    - "clear" (the resource can be cleared or removed)
                                    - "edit" (the resource can be appended-to or child records can be added)
                                    and so forth.

                                    this means representations can look like this:
                                    <shopping-cart>
                                      <link href="..." rel="collection http://example.com/rels/shopping-cart" state="read clear" />
                                      <items count="9">
                                        <item href="..." rel="item http://example.com/rels/book" state="read clear">
                                          ...
                                        </item>
                                        ...
                                      </items>
                                    </shopping-cart>

                                    or you can use a much more explicit design:
                                    <shopping-cart>
                                      <clear href="..." rel="collection http://example.com/rels/shopping-cart" />
                                      <read href="..." rel="collection http://example.com/rels/shopping-cart" />
                                      <items count="9">
                                        <item>
                                          <clear href="..." rel="item http://example.com/rels/book" />
                                          <read href="..." rel="item http://example.com/rels/book" />
                                          ...
                                        </item>
                                        ...
                                      </items>
                                    </shopping-cart>

                                    These are just two possibilities. Note that i didn't include a protocol method in these designs, but that would be possible, too. an explicit example (one that might support more than one protocol) might look like this:
                                    <shopping-cart>
                                      <clear href="..." rel="collection http://example.com/rels/shopping-cart" method="HTTP.DELETE"/>
                                      <read href="..." rel="collection http://example.com/rels/shopping-cart" method="HTTP.GET"/>
                                      <items count="9">
                                        ...
                                      </items>
                                    </shopping-cart>

                                    Again, this is design so there are many possibilities.

                                    <snip>
                                    Also where in this context fit the concept of forms, allowing user to fill in some parameters...
                                    </snip>

                                    yes, i use forms quite often. this is about what state needs to be transferred from the client to the server (usually we only think about transferring state from server to client!). I might have a server that requires additional data in order to add an item to a cart:

                                      <data name="quantity" value="1" />
                                      <date name="stockid" value="q1w2e3" />
                                      <date name="required-delivery-date" value="2013-12-24" />
                                    </link>
                                    and so forth.

                                    I am in the habit of including forms in responses[0]. However, some folks prefer to only include links to forms and keep the forms as stand-alone resources[1]. Still others think it best not to include this information at all and keep that information as part of the documentation[2]

                                    Again, these are design decisions you can make on your own when creating your own message format (media type) or one that you can use to guide which of the existing registered types will best fit your needs/aesthetics.

                                    Cheers.







                                    On Sat, Nov 9, 2013 at 5:46 PM, Philippe Marsteau <marsteau@...> wrote:
                                    Interesting... 

                                    Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...

                                    Also where in this context fit the concept of forms, allowing user to fill in some parameters, before user can actually add the book in the shipping cart (eg, number of books to add)? Would the representation include a link to the form (instead of to the shopping cart directly), and its doc states only GET is allowed? The idea is to let user discover which attributes are need as input before a PUT (or POST or PATCH) can be called on the shopping cart... Instead of having client to hard code editable input fields to be requested to user ("knowing" the media type or profile of the shopping cart resource).

                                    Thanks again, it helps.

                                    Phil

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

                                    FWIW, you're getting in to "design" space here - and that's based on context and preference. nothing right/wrong here so there are lots of options.

                                    first, i usually indicate state properties of a resource using data elements in the representation, not transition elements:

                                    <book>
                                      <in-stock value="true" />
                                      <link href="..." rel="http://example.com/rels/shopping-cart" />
                                    </book>

                                    again, instructions on the link identified as the shopping cart might look like this:
                                    - HTTP.GET returns the state of the shopping cart
                                    - HTTP.POST adds the current book to the shopping cart
                                    - HTTP.DELETE clears all items from the shopping cart
                                    and so on...

                                    now clients (humans) can see that the "state" of the book is "in-stock" and then decide to take an appropriate action.


                                    as for "I believe there are cases where the server dictates the steps before"...

                                    yes, the server may have rules about what "state" server-side resources need to have before a task can be executed. This can be viewed as dictating that "state" of things on the server, not dictating the order in which things happen on the client. This POV is close to the way programmers had to (re)learn to design user interfaces with teh advent of the pointer device (mouse). Suddenly, users could not be "led" from input to input in a certain order. Users had be power (and audacity) to click around on the screen, enter things in various order and so on. It was bedlam (grin)!

                                    eventually, we learned to build UIs that used things like progressive disclosure, disabling items until certain "state" in the UI is achieved, etc.

                                    we need to do that same for hypermedia services on the web. 

                                    hope this helps.




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




                                  • mike amundsen
                                    A key requirement for me is to reduce as much as possible coupling, therefore I try to design resources as generically as possible (a list of simple
                                    Message 17 of 25 , Nov 9, 2013
                                    • 0 Attachment
                                      <snip>
                                      A key requirement for me is to reduce as much as possible coupling, therefore I try to design resources as generically as possible (a list of simple attributes and a list of relationships/states) with the goal to allow for maximum evolvability of the API - given the mostly UI-driven interactions against the API. 
                                      </snip>

                                      If you favor JSON and want to reduce coupling between internal coding and the shared messages, I highly recommend one of the recently-registered hypermedia types such as HAL+JSON[1], Collection+JSON[2], and Siren[3]. I find each of these has a unique strength and all of them do a good job of leading you toward SoC between local components and shared state messages.

                                      By treating the message as a structured format independent of your problem domain (books, etc.) you get quite far down the path of decoupled communications. HTML has been successful at this for more than a decade; our servers continually transform local business objects in the this format and enable applications running in a client app that knows nothing of the problem domain, but *does* understand the message format and the protocol details express _within_ the message (HTML.A, HTML.IMG, HTML.FORM).

                                      <snip>What about the others experience with forms resources vs strongly typed links?</snip>

                                      Yes, this convo has gotten a bit narrow since I am dominating the thread. I know there are several others here who have experience in this space, too.

                                      Cheers.






                                      On Sat, Nov 9, 2013 at 7:14 PM, Philippe Marsteau <marsteau@...> wrote:
                                      Thank you Mike. That clarifies a lot. 

                                      I think I misunderstood link relationships vs. capabilities/states. Your proposed approaches help me see how to better design this. 

                                      A key requirement for me is to reduce as much as possible coupling, therefore I try to design resources as generically as possible (a list of simple attributes and a list of relationships/states) with the goal to allow for maximum evolvability of the API - given the mostly UI-driven interactions against the API. 

                                      Basically, I try to map the web pages one would interact with from a browser, but stripping out the UI elements (using generic JSON like format).

                                      By keeping the media type as low entry barrier (simple) as possible, assuming client will mostly render the data in its preferred technology, adding attributes or actions becomes highly dynamic without requiring consumer to "uptake" changes: attributes appear dynamically in UI front end and new interactions (think of "more actions" drop box) becomes added dynamically as well. I think your CJ media type is pretty generic too, so maybe this idea/goal is familiar to you...

                                      I also understand this might not fit for system to system type of interactions (scripted/automated integrations) and my goal might be too idealistic. Have you seen such type of REST APIs? Am I heading in the right direction?

                                      What about the others experience with forms resources vs strongly typed links?

                                      Phil

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

                                      <snip>
                                      Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...
                                      </snip>

                                      If you wish to communicate this level of detail to clients (not at all a bad thing) often people think of these as _actions_ instead of states and just communicate the possible action:
                                      rel="clear"
                                      rel="add-book"
                                      and so forth.

                                      I try to steer clear of that whenever possible (as a design goal) and express these things as "states" on the server that need to be communicated to the client. for example (just making this up here...):
                                      - "clear" (the resource can be cleared or removed)
                                      - "edit" (the resource can be appended-to or child records can be added)
                                      and so forth.

                                      this means representations can look like this:
                                      <shopping-cart>
                                        <link href="..." rel="collection http://example.com/rels/shopping-cart" state="read clear" />
                                        <items count="9">
                                          <item href="..." rel="item http://example.com/rels/book" state="read clear">
                                            ...
                                          </item>
                                          ...
                                        </items>
                                      </shopping-cart>

                                      or you can use a much more explicit design:
                                      <shopping-cart>
                                        <clear href="..." rel="collection http://example.com/rels/shopping-cart" />
                                        <read href="..." rel="collection http://example.com/rels/shopping-cart" />
                                        <items count="9">
                                          <item>
                                            <clear href="..." rel="item http://example.com/rels/book" />
                                            <read href="..." rel="item http://example.com/rels/book" />
                                            ...
                                          </item>
                                          ...
                                        </items>
                                      </shopping-cart>

                                      These are just two possibilities. Note that i didn't include a protocol method in these designs, but that would be possible, too. an explicit example (one that might support more than one protocol) might look like this:
                                      <shopping-cart>
                                        <clear href="..." rel="collection http://example.com/rels/shopping-cart" method="HTTP.DELETE"/>
                                        <read href="..." rel="collection http://example.com/rels/shopping-cart" method="HTTP.GET"/>
                                        <items count="9">
                                          ...
                                        </items>
                                      </shopping-cart>

                                      Again, this is design so there are many possibilities.

                                      <snip>
                                      Also where in this context fit the concept of forms, allowing user to fill in some parameters...
                                      </snip>

                                      yes, i use forms quite often. this is about what state needs to be transferred from the client to the server (usually we only think about transferring state from server to client!). I might have a server that requires additional data in order to add an item to a cart:

                                        <data name="quantity" value="1" />
                                        <date name="stockid" value="q1w2e3" />
                                        <date name="required-delivery-date" value="2013-12-24" />
                                      </link>
                                      and so forth.

                                      I am in the habit of including forms in responses[0]. However, some folks prefer to only include links to forms and keep the forms as stand-alone resources[1]. Still others think it best not to include this information at all and keep that information as part of the documentation[2]

                                      Again, these are design decisions you can make on your own when creating your own message format (media type) or one that you can use to guide which of the existing registered types will best fit your needs/aesthetics.

                                      Cheers.







                                      On Sat, Nov 9, 2013 at 5:46 PM, Philippe Marsteau <marsteau@...> wrote:
                                      Interesting... 

                                      Now how do I tell in this book representation that at this time, clearing the shopping cart or adding the book to the shipping cart is not allowed (eg based on authenticated user permissions) but reading it is allowed? I wish user could discover from the representation rather than having to call OPTIONS or learning after the fact (error message)...

                                      Also where in this context fit the concept of forms, allowing user to fill in some parameters, before user can actually add the book in the shipping cart (eg, number of books to add)? Would the representation include a link to the form (instead of to the shopping cart directly), and its doc states only GET is allowed? The idea is to let user discover which attributes are need as input before a PUT (or POST or PATCH) can be called on the shopping cart... Instead of having client to hard code editable input fields to be requested to user ("knowing" the media type or profile of the shopping cart resource).

                                      Thanks again, it helps.

                                      Phil

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

                                      FWIW, you're getting in to "design" space here - and that's based on context and preference. nothing right/wrong here so there are lots of options.

                                      first, i usually indicate state properties of a resource using data elements in the representation, not transition elements:

                                      <book>
                                        <in-stock value="true" />
                                        <link href="..." rel="http://example.com/rels/shopping-cart" />
                                      </book>

                                      again, instructions on the link identified as the shopping cart might look like this:
                                      - HTTP.GET returns the state of the shopping cart
                                      - HTTP.POST adds the current book to the shopping cart
                                      - HTTP.DELETE clears all items from the shopping cart
                                      and so on...

                                      now clients (humans) can see that the "state" of the book is "in-stock" and then decide to take an appropriate action.


                                      as for "I believe there are cases where the server dictates the steps before"...

                                      yes, the server may have rules about what "state" server-side resources need to have before a task can be executed. This can be viewed as dictating that "state" of things on the server, not dictating the order in which things happen on the client. This POV is close to the way programmers had to (re)learn to design user interfaces with teh advent of the pointer device (mouse). Suddenly, users could not be "led" from input to input in a certain order. Users had be power (and audacity) to click around on the screen, enter things in various order and so on. It was bedlam (grin)!

                                      eventually, we learned to build UIs that used things like progressive disclosure, disabling items until certain "state" in the UI is achieved, etc.

                                      we need to do that same for hypermedia services on the web. 

                                      hope this helps.




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





                                    • Jan Algermissen
                                      ... Make the state a resource and modify that: PUT /playlist/77626/state Content-Type: application/vnd.foo.state live Personally, I aim for
                                      Message 18 of 25 , Nov 10, 2013
                                      • 0 Attachment
                                        On 08.11.2013, at 00:10, Charles Reese <charles.reese@...> wrote:

                                        >
                                        > Hi Mike,
                                        >
                                        > Thank you so much!
                                        >
                                        > I'm still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a playlist, it defaults to 'private'. I want to turn it public. I could use a link rel like this:
                                        >
                                        > /rel/playlist/publish
                                        >
                                        > But again, I'm not using the method as the "verb". How would you handle this?

                                        Make the state a resource and modify that:

                                        PUT /playlist/77626/state
                                        Content-Type: application/vnd.foo.state

                                        <state>live</state>

                                        Personally, I aim for avoiding the need to introduce a media type for this and use a flag and the creational semantics of PUT:

                                        PUT /playlist/77626/flags/isLiveFlag
                                        Content-Length: 0

                                        201 Created
                                        ....

                                        Note that you even get create-if-not-exists semantisc when using If-None-Match: *

                                        Dig deeper here: http://www.xent.com/pipermail/fork/2001-September/004712.html

                                        Jan







                                        >
                                        > Cheers,
                                        > Charles
                                        >
                                        >
                                        > On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <mamund@...> wrote:
                                        > Charles:
                                        >
                                        > First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
                                        > - IANA [1]
                                        > - microformats [2]
                                        > - Dublin Core [3]
                                        >
                                        > When you *do* use them, be sure to mention in your documentation which are used and where they are registered.
                                        >
                                        > Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.
                                        >
                                        > Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:
                                        >
                                        > insert-song -> song (w/ HTTP.POST)
                                        > remove-song -> song (w/ HTTP.DELETE)
                                        >
                                        > Cheers.
                                        >
                                        > [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
                                        > [2] http://microformats.org/wiki/existing-rel-values
                                        > [3] http://dublincore.org/documents/dcmi-terms/
                                        > [4] http://tools.ietf.org/html/rfc5988
                                        >
                                        >
                                        >
                                        > mamund
                                        > +1.859.757.1449
                                        > skype: mca.amundsen
                                        > http://amundsen.com/blog/
                                        > http://twitter.com/mamund
                                        > https://github.com/mamund
                                        > http://www.linkedin.com/in/mamund
                                        >
                                        >
                                        > On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:
                                        >
                                        >
                                        > Hi all,
                                        >
                                        > I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.
                                        >
                                        > Here is what I'm considering:
                                        >
                                        > Option 1:
                                        >
                                        > /rels/playlists
                                        > /rels/playlist
                                        > /rels/playlist/insert-song
                                        > /rels/playlist/remove-song
                                        >
                                        > Option 2:
                                        >
                                        > /rels/playlist
                                        > /rels/playlist/create
                                        > /rels/playlist/edit
                                        > /rels/playlist/delete
                                        > /rels/playlist/insert-song
                                        > /rels/playlist/remove-song
                                        >
                                        > Option 3:
                                        >
                                        > list
                                        > create
                                        > edit
                                        > delete
                                        > insert-song
                                        > remove-song
                                        >
                                        > The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.
                                        >
                                        > Which of these is preferred? Are there better options?
                                        >
                                        > Charles
                                        >
                                        >
                                        >
                                        >
                                        >
                                        >
                                      • Jan Algermissen
                                        ... And another option is to move the resource into the right collection. E.g. by putting an entry in an AtomPub collection that represents the
                                        Message 19 of 25 , Nov 10, 2013
                                        • 0 Attachment
                                          On 08.11.2013, at 00:10, Charles Reese <charles.reese@...> wrote:

                                          >
                                          > Hi Mike,
                                          >
                                          > Thank you so much!
                                          >
                                          > I'm still wondering about link rels for state-transitions affecting only one resource. For example, suppose when creating a playlist, it defaults to 'private'. I want to turn it public. I could use a link rel like this:
                                          >
                                          > /rel/playlist/publish
                                          >
                                          > But again, I'm not using the method as the "verb". How would you handle this?

                                          And another option is to 'move' the resource into the right collection. E.g. by putting an entry in an AtomPub collection that represents the live-playlists.

                                          If you think of this as a queue, you are actually creating a better API, because 'publishing' is never a matter of the client actually doing it. Rather, the client 'marks' it for publishing - so the server can do it, when it has the time and resources to do so. Hence: queue semantics.

                                          Jan





                                          >
                                          > Cheers,
                                          > Charles
                                          >
                                          >
                                          > On Wed, Nov 6, 2013 at 7:09 AM, mike amundsen <mamund@...> wrote:
                                          > Charles:
                                          >
                                          > First, if you use single strings ("edit", etc.) be sure they are registered Link Relation Values. Here's a good list of references:
                                          > - IANA [1]
                                          > - microformats [2]
                                          > - Dublin Core [3]
                                          >
                                          > When you *do* use them, be sure to mention in your documentation which are used and where they are registered.
                                          >
                                          > Next, for the cases where you can't find Link Rel Values that suit your needs, use the 5988[4] rules for creating full URIs (not relative) and make them URLs (resolvable) that point to your own documentation/glossary of Link Rel Values online.
                                          >
                                          > Finally, when minting your own Link Rel Values, aim for describing the relation between the two resources instead of the action to commit on the "target" resource. Use protocol methods to express the "action" to commit:
                                          >
                                          > insert-song -> song (w/ HTTP.POST)
                                          > remove-song -> song (w/ HTTP.DELETE)
                                          >
                                          > Cheers.
                                          >
                                          > [1] http://www.iana.org/assignments/link-relations/link-relations.xhtml
                                          > [2] http://microformats.org/wiki/existing-rel-values
                                          > [3] http://dublincore.org/documents/dcmi-terms/
                                          > [4] http://tools.ietf.org/html/rfc5988
                                          >
                                          >
                                          >
                                          > mamund
                                          > +1.859.757.1449
                                          > skype: mca.amundsen
                                          > http://amundsen.com/blog/
                                          > http://twitter.com/mamund
                                          > https://github.com/mamund
                                          > http://www.linkedin.com/in/mamund
                                          >
                                          >
                                          > On Tue, Nov 5, 2013 at 9:52 PM, Charles Reese <charles.reese@...> wrote:
                                          >
                                          >
                                          > Hi all,
                                          >
                                          > I'm looking at HAL and Collection+JSON for an API I'm building. I was wondering if there are any community norms for constructing link relations.
                                          >
                                          > Here is what I'm considering:
                                          >
                                          > Option 1:
                                          >
                                          > /rels/playlists
                                          > /rels/playlist
                                          > /rels/playlist/insert-song
                                          > /rels/playlist/remove-song
                                          >
                                          > Option 2:
                                          >
                                          > /rels/playlist
                                          > /rels/playlist/create
                                          > /rels/playlist/edit
                                          > /rels/playlist/delete
                                          > /rels/playlist/insert-song
                                          > /rels/playlist/remove-song
                                          >
                                          > Option 3:
                                          >
                                          > list
                                          > create
                                          > edit
                                          > delete
                                          > insert-song
                                          > remove-song
                                          >
                                          > The first option mixes the singular and plural for items and collections. Then it tacks on a few actions for what doesn't fit well with CRUD. The last option makes the state transitions explicit (but doesn't allow linking for docs). The middle option is somewhat in between.
                                          >
                                          > Which of these is preferred? Are there better options?
                                          >
                                          > Charles
                                          >
                                          >
                                          >
                                          >
                                          >
                                          >
                                        • Erik Wilde
                                          hey jan. ... why create a separate media type? you re designing the playlist media type anyway, including a fragment that s embedded in the playlist
                                          Message 20 of 25 , Nov 10, 2013
                                          • 0 Attachment
                                            hey jan.

                                            > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                            > Make the state a resource and modify that:
                                            >
                                            > PUT /playlist/77626/state
                                            > Content-Type: application/vnd.foo.state
                                            >
                                            > <state>live</state>
                                            >
                                            > Personally, I aim for avoiding the need to introduce a media type for this ...

                                            why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                            cheers,

                                            dret.
                                          • Charles Reese
                                            Jan, Mike, dret: I guess publishing is a bad example. As dret writes, I can use a status field and watch when it changes. So... a better one. Suppose you want
                                            Message 21 of 25 , Nov 10, 2013
                                            • 0 Attachment
                                              Jan, Mike, dret:

                                              I guess publishing is a bad example. As dret writes, I can use a status field and watch when it changes.

                                              So... a better one. 

                                              Suppose you want to create a dashboard for Twitter to manage all your friends. You can start by creating a resource with a link relation called "https:/friender.com/rels/friends" along with the usual methods: 

                                              POST: to follow
                                              DELETE: to stop following
                                              GET: returns a list of all your friends .

                                              But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                              Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                              I'm wondering how you all would approach.

                                              Cheers,
                                              Charles


                                              On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:
                                              hey jan.

                                              > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                              > Make the state a resource and modify that:
                                              >
                                              > PUT /playlist/77626/state
                                              > Content-Type: application/vnd.foo.state
                                              >
                                              > <state>live</state>
                                              >
                                              > Personally, I aim for avoiding the need to introduce a media type for this ...

                                              why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                              cheers,

                                              dret.



                                              On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:
                                              hey jan.

                                              > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                              > Make the state a resource and modify that:
                                              >
                                              > PUT /playlist/77626/state
                                              > Content-Type: application/vnd.foo.state
                                              >
                                              > <state>live</state>
                                              >
                                              > Personally, I aim for avoiding the need to introduce a media type for this ...

                                              why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                              cheers,

                                              dret.

                                            • mike amundsen
                                              But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users
                                              Message 22 of 25 , Nov 10, 2013
                                              • 0 Attachment
                                                <snip>
                                                But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                                Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                                I'm wondering how you all would approach.
                                                </snip>

                                                LOL! are you just making sh*t up to see what we come up with?

                                                if you what you need to do is offer a sync service, then create a resource that exposes the required state and allow clients to manipulate that state via representations using a hypermedia control that describes the representation transfer.  

                                                Here's a possible solution to manipulating state between two storage locations that the server already associates w/ your login-context (e.g. no need for the client to tell the server what locations to sync up).

                                                <sync href="..." rel="http://example.com/rels/friends" />
                                                HTTP.GET to return the status of your sync state (e.g. are you in-sync or not?)
                                                HTTP.POST to initiate the sync process 
                                                and so forth.

                                                Of course, if you want to create a more complicated state management case; one where the client is allowed to select one or both of the storage locations for syncing, then you need a hypermedia control that allows clients to include this additional state information:

                                                // Just how the client would *know* these values is another matter but you can work that out as needed.
                                                <sync href="..." rel="http://example.com/rels/friends">
                                                  <data name="source" value="" />
                                                  <data name="target" value="" />
                                                </sync>
                                                HTTP.POST to initiate the sync process 
                                                and so forth.

                                                In this case, the POST action might return a 201 w/ Location showing a resource that representations the state of the sync progress. There are other possibilities, too.

                                                Keep in mind you are not managing *objects* (e.g. friends) here, you are manipulating state by exchanging representations (hence the name REpresentational State Transfer). 

                                                Cheers.







                                                On Sun, Nov 10, 2013 at 1:10 PM, Charles Reese <charles.reese@...> wrote:


                                                Jan, Mike, dret:

                                                I guess publishing is a bad example. As dret writes, I can use a status field and watch when it changes.

                                                So... a better one. 

                                                Suppose you want to create a dashboard for Twitter to manage all your friends. You can start by creating a resource with a link relation called "https:/friender.com/rels/friends" along with the usual methods: 

                                                POST: to follow
                                                DELETE: to stop following
                                                GET: returns a list of all your friends .

                                                But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                                Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                                I'm wondering how you all would approach.

                                                Cheers,
                                                Charles


                                                On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:

                                                hey jan.

                                                > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                                > Make the state a resource and modify that:
                                                >
                                                > PUT /playlist/77626/state
                                                > Content-Type: application/vnd.foo.state
                                                >
                                                > <state>live</state>
                                                >
                                                > Personally, I aim for avoiding the need to introduce a media type for this ...

                                                why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                                cheers,

                                                dret.



                                                On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:
                                                hey jan.

                                                > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                                > Make the state a resource and modify that:
                                                >
                                                > PUT /playlist/77626/state
                                                > Content-Type: application/vnd.foo.state
                                                >
                                                > <state>live</state>
                                                >
                                                > Personally, I aim for avoiding the need to introduce a media type for this ...

                                                why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                                cheers,

                                                dret.




                                              • Charles Reese
                                                ... Yes and no. There are so many *bad* examples, it s hard to find good ones from which to learn. I do need syncing/ingestion for what I m doing. My questions
                                                Message 23 of 25 , Nov 10, 2013
                                                • 0 Attachment
                                                  > LOL! are you just making sh*t up to see what we come up with?

                                                  Yes and no. There are so many *bad* examples, it's hard to find good ones from which to learn. I do need syncing/ingestion for what I'm doing. My questions are really about the right way to expose this functionality via hypermedia controls, what to use for rel values, and so on. Right now, leaning towards this:

                                                  { "collection" :
                                                    "version : "1.0",
                                                      .
                                                      .
                                                      .
                                                    "links" : [
                                                      { "href" : "https://friender.com/api/sync/friends", "rel" : "sync" }
                                                    ]
                                                      .
                                                      .
                                                      .
                                                  }


                                                  On Sun, Nov 10, 2013 at 11:17 AM, mike amundsen <mamund@...> wrote:
                                                  <snip>
                                                  But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                                  Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                                  I'm wondering how you all would approach.
                                                  </snip>

                                                  LOL! are you just making sh*t up to see what we come up with?

                                                  if you what you need to do is offer a sync service, then create a resource that exposes the required state and allow clients to manipulate that state via representations using a hypermedia control that describes the representation transfer.  

                                                  Here's a possible solution to manipulating state between two storage locations that the server already associates w/ your login-context (e.g. no need for the client to tell the server what locations to sync up).

                                                  <sync href="..." rel="http://example.com/rels/friends" />
                                                  HTTP.GET to return the status of your sync state (e.g. are you in-sync or not?)
                                                  HTTP.POST to initiate the sync process 
                                                  and so forth.

                                                  Of course, if you want to create a more complicated state management case; one where the client is allowed to select one or both of the storage locations for syncing, then you need a hypermedia control that allows clients to include this additional state information:

                                                  // Just how the client would *know* these values is another matter but you can work that out as needed.
                                                  <sync href="..." rel="http://example.com/rels/friends">
                                                    <data name="source" value="" />
                                                    <data name="target" value="" />
                                                  </sync>
                                                  HTTP.POST to initiate the sync process 
                                                  and so forth.

                                                  In this case, the POST action might return a 201 w/ Location showing a resource that representations the state of the sync progress. There are other possibilities, too.

                                                  Keep in mind you are not managing *objects* (e.g. friends) here, you are manipulating state by exchanging representations (hence the name REpresentational State Transfer). 

                                                  Cheers.




                                                  On Sun, Nov 10, 2013 at 1:10 PM, Charles Reese <charles.reese@...> wrote:


                                                  Jan, Mike, dret:

                                                  I guess publishing is a bad example. As dret writes, I can use a status field and watch when it changes.

                                                  So... a better one. 

                                                  Suppose you want to create a dashboard for Twitter to manage all your friends. You can start by creating a resource with a link relation called "https:/friender.com/rels/friends" along with the usual methods: 

                                                  POST: to follow
                                                  DELETE: to stop following
                                                  GET: returns a list of all your friends .

                                                  But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                                  Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                                  I'm wondering how you all would approach.

                                                  Cheers,
                                                  Charles


                                                  On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:

                                                  hey jan.

                                                  > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                                  > Make the state a resource and modify that:
                                                  >
                                                  > PUT /playlist/77626/state
                                                  > Content-Type: application/vnd.foo.state
                                                  >
                                                  > <state>live</state>
                                                  >
                                                  > Personally, I aim for avoiding the need to introduce a media type for this ...

                                                  why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                                  cheers,

                                                  dret.



                                                  On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:
                                                  hey jan.

                                                  > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                                  > Make the state a resource and modify that:
                                                  >
                                                  > PUT /playlist/77626/state
                                                  > Content-Type: application/vnd.foo.state
                                                  >
                                                  > <state>live</state>
                                                  >
                                                  > Personally, I aim for avoiding the need to introduce a media type for this ...

                                                  why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                                  cheers,

                                                  dret.





                                                • mike amundsen
                                                  yep - that could work. but are you planning on doing a GET for that link? That looks liked a Cj representation and in Cj the links:[] and queries:[] arrays
                                                  Message 24 of 25 , Nov 10, 2013
                                                  • 0 Attachment
                                                    yep - that could work. but are you planning on doing a GET for that link? 

                                                    That looks liked a Cj representation and in Cj the links:[] and queries:[] arrays support HTTP.GET.  
                                                    The template supports POST & PUT. 
                                                    The href on items supports GET and DELETE.

                                                    You MAY want to use the link to point to another Cj representation that exposes the sync details (in the items?) and has a template that includes the state that needs to be transferred from client to server when initiating a "sync" operation.

                                                    Just some ideas.





                                                    On Sun, Nov 10, 2013 at 6:04 PM, Charles Reese <charles.reese@...> wrote:


                                                    > LOL! are you just making sh*t up to see what we come up with?

                                                    Yes and no. There are so many *bad* examples, it's hard to find good ones from which to learn. I do need syncing/ingestion for what I'm doing. My questions are really about the right way to expose this functionality via hypermedia controls, what to use for rel values, and so on. Right now, leaning towards this:

                                                    { "collection" :
                                                      "version : "1.0",
                                                        .
                                                        .
                                                        .
                                                      "links" : [
                                                        { "href" : "https://friender.com/api/sync/friends", "rel" : "sync" }
                                                      ]
                                                        .
                                                        .
                                                        .
                                                    }


                                                    On Sun, Nov 10, 2013 at 11:17 AM, mike amundsen <mamund@...> wrote:
                                                    <snip>
                                                    But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                                    Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                                    I'm wondering how you all would approach.
                                                    </snip>

                                                    LOL! are you just making sh*t up to see what we come up with?

                                                    if you what you need to do is offer a sync service, then create a resource that exposes the required state and allow clients to manipulate that state via representations using a hypermedia control that describes the representation transfer.  

                                                    Here's a possible solution to manipulating state between two storage locations that the server already associates w/ your login-context (e.g. no need for the client to tell the server what locations to sync up).

                                                    <sync href="..." rel="http://example.com/rels/friends" />
                                                    HTTP.GET to return the status of your sync state (e.g. are you in-sync or not?)
                                                    HTTP.POST to initiate the sync process 
                                                    and so forth.

                                                    Of course, if you want to create a more complicated state management case; one where the client is allowed to select one or both of the storage locations for syncing, then you need a hypermedia control that allows clients to include this additional state information:

                                                    // Just how the client would *know* these values is another matter but you can work that out as needed.
                                                    <sync href="..." rel="http://example.com/rels/friends">
                                                      <data name="source" value="" />
                                                      <data name="target" value="" />
                                                    </sync>
                                                    HTTP.POST to initiate the sync process 
                                                    and so forth.

                                                    In this case, the POST action might return a 201 w/ Location showing a resource that representations the state of the sync progress. There are other possibilities, too.

                                                    Keep in mind you are not managing *objects* (e.g. friends) here, you are manipulating state by exchanging representations (hence the name REpresentational State Transfer). 

                                                    Cheers.




                                                    On Sun, Nov 10, 2013 at 1:10 PM, Charles Reese <charles.reese@...> wrote:


                                                    Jan, Mike, dret:

                                                    I guess publishing is a bad example. As dret writes, I can use a status field and watch when it changes.

                                                    So... a better one. 

                                                    Suppose you want to create a dashboard for Twitter to manage all your friends. You can start by creating a resource with a link relation called "https:/friender.com/rels/friends" along with the usual methods: 

                                                    POST: to follow
                                                    DELETE: to stop following
                                                    GET: returns a list of all your friends .

                                                    But there is an edge case... Last week, there was a Category 5 hurricane that went right through data center, and while your site was down, your users went to plain-old Twitter and added some friends.

                                                    Now your dashboard and twitter are out of sync. We need to be able to add "friends" without creating them on Twitter.

                                                    I'm wondering how you all would approach.

                                                    Cheers,
                                                    Charles


                                                    On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:

                                                    hey jan.

                                                    > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                                    > Make the state a resource and modify that:
                                                    >
                                                    > PUT /playlist/77626/state
                                                    > Content-Type: application/vnd.foo.state
                                                    >
                                                    > <state>live</state>
                                                    >
                                                    > Personally, I aim for avoiding the need to introduce a media type for this ...

                                                    why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                                    cheers,

                                                    dret.



                                                    On Sun, Nov 10, 2013 at 8:42 AM, Erik Wilde <dret@...> wrote:
                                                    hey jan.

                                                    > On Nov 10, 2013, at 2:23, Jan Algermissen <jan.algermissen@...> wrote:
                                                    > Make the state a resource and modify that:
                                                    >
                                                    > PUT /playlist/77626/state
                                                    > Content-Type: application/vnd.foo.state
                                                    >
                                                    > <state>live</state>
                                                    >
                                                    > Personally, I aim for avoiding the need to introduce a media type for this ...

                                                    why create a separate media type? you're designing the playlist media type anyway, including a fragment that's embedded in the playlist representation to indicate the playlist status. simply allow PUT on a linked sub-resource with the exact same syntax. all you have to do is create a new document/message type in your media type: problem solved.

                                                    cheers,

                                                    dret.








                                                  • Steve Klabnik
                                                    ... An easy way to get started thinking about how to tackle these problems is WWWWWD? (What would the world wide web do?) I would have come to the same
                                                    Message 25 of 25 , Nov 13, 2013
                                                    • 0 Attachment
                                                      On 11/11/2013 12:04 AM, Charles Reese wrote:
                                                      > There are so many *bad* examples, it's hard to find good ones from which
                                                      > to learn.

                                                      An easy way to get started thinking about how to tackle these problems
                                                      is WWWWWD? (What would the world wide web do?)

                                                      I would have come to the same conclusion as Mike, but my initial thought
                                                      process would have been like this: What websites do I use that tackle
                                                      this kind of problem?

                                                      In my brain, I go to https://www.beeminder.com/ . I use this to keep
                                                      track of my DuoLingo scores, to make sure I'm keeping up with my German.

                                                      So, if Beeminder gets out of whack, there's a little button I can press
                                                      (read: hypermedia control) that says "re-sync data." That initiates a
                                                      background process to re-fetch the data and make it match. It redirects
                                                      back to the dashboard page, with a little "now syncing, check back
                                                      later" and a graphic to indicate that the synching process is taking
                                                      place. Said control is disabled until the process is done. In addition,
                                                      this process runs once a day, even if I don't activate the control.

                                                      Anyway, this isn't perfect in all cases, but I often find it a good
                                                      starting point when thinking about how to model a particular kind of
                                                      state machine.
                                                    Your message has been successfully submitted and would be delivered to recipients shortly.