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

Re: link relations discussion [was: [rest-discuss] Encoding reuse but new content types?

Expand Messages
  • Solomon Duskis
    Tim, I fully agree with you here. I keep taking a look at HTML (which Roy was and is heavily involved with) for inspiration as a key component in moving the
    Message 1 of 22 , Oct 2, 2009
    • 0 Attachment
      Tim,

      I fully agree with you here.  I keep taking a look at HTML (which Roy was and is heavily involved with) for inspiration as a key component in moving the universal aspects of HATEOAS forward.  While I don't think that HTML is perfect for data oriented APIs, it seems to have quite a few better ingredients than atom in relation to hypertext description.

      I hope that this kind of discussion does continue.

      -Solomon

      On Fri, Oct 2, 2009 at 9:27 AM, Tim Williams <williamstw@...> wrote:
       

      On Fri, Oct 2, 2009 at 9:12 AM, Bill Burke <bburke@...> wrote:
      >
      >
      > Tim Williams wrote:
      >>
      >>
      >> On Thu, Oct 1, 2009 at 8:09 AM, Tim Williams <williamstw@...
      >> <mailto:williamstw%40gmail.com>> wrote:
      >>  > On Wed, Sep 30, 2009 at 4:06 PM, Roy T. Fielding <fielding@...
      >> <mailto:fielding%40gbiv.com>> wrote:
      >>  >> On Sep 30, 2009, at 12:56 PM, Tim Williams wrote:
      >>  >>
      >>  >>> Roy says[0], "A REST API should spend almost all of its descriptive
      >>  >>> effort in defining the media type(s) used for representing resources
      >>  >>> and driving application state, or in defining extended relation names
      >>  >>> and/or hypertext-enabled mark-up for existing standard media types."
      >>  >>>
      >>  >>> I have situations where formats such as Atom are fairly well-suited
      >> to
      >>  >>> represent my resources.  If I re-use the format and keep the content
      >>  >>> type "atom+xml", then client's wouldn't know my specific usage of
      >> atom
      >>  >>> (e.g. semantics behind some of my "rel" attributes).
      >>  >>
      >>  >> Link relations are universal, independent of the format in
      >>  >> which they are found, though perhaps only used with a target
      >>  >> that is in a specific format (by practice, not by standard).
      >>  >> The fact that some media type specifications also introduce
      >>  >> new link relations does not make the relations specific to
      >>  >> those media types.
      >>  >
      >>  > The more I look into link relations, the messier it gets.  I'm
      >>  > wondering if there's a mailing list/group/etc where discussions on
      >>  > link relations take place?  For example, I'm looking for an
      >>  > appropriate link relation for:
      >>  >
      >>  > o) a project descriptor (DOAP) - it seems that rel=meta is in common
      >>  > use but I haven't found a spec where it's defined yet.
      >>
      >> In partial answer to my own question, META seems defined here:
      >>
      >> http://www.w3.org/TR/relations.html <http://www.w3.org/TR/relations.html>
      >>
      >
      > So where (or if) do Links + URI Templates come in?  Is it ok to define a
      > link relationship that is a template following RFC-xxx and to specify in the
      > link definition what template parameters are expected when following the
      > link template?
      >
      > for example:
      >
      > <link rel="CustomersByZip"
      > template="http://example.com/customers?zip={zipcode}" type="xml"/>
      >
      >
      > In the "CustomerByZip" definition, it say that "zipcode" is a parameter you
      > have to provide to the URL.
      >
      > The URI remains mostly opaque, but the user is still providing input.

      Well, I'm just now fully grasping this
      "link-relations-are-universal-and-independent-of-media-type" thing,
      but precedence has been set I think. The OpenSearch spec[0]
      introduced the rel=results link relation, which is essentially that.
      I'm not yet smart enough to know if that's a Good Thing or not.

      The more I learn about this, I'm gathering that the reality of the
      current state of link-relations is a good bit behind Roy's universal
      ideal. They're such an essential part of HATEOAS, I'm surprised by
      the overall lack of discussion around them.

      --tim

      [0] - http://www.opensearch.org/Specifications/OpenSearch/1.1#The_.22Url.22_element


    • Bill Burke
      ... I ve said this before when you posted this idea...But... is rendering metadata meant to help a *Human Being* make a decision. Machine based clients
      Message 2 of 22 , Oct 2, 2009
      • 0 Attachment
        Solomon Duskis wrote:
        > Using link doesn't seem all that natural to me. In HTML that question
        > is answered pretty simply:
        >
        > <form action="http://example.com/customers
        > <http://example.com/customers?zip=>" method="GET" name="CustomersByZip">
        > <input type="text" name="zip" />
        > </form>
        >

        I've said this before when you posted this idea...But...

        <form> is rendering metadata meant to help a *Human Being* make a
        decision. Machine based clients are already going to know how to fill
        out the "form" ahead of time so the rendering information isn't needed
        when transmitting representations. Only the link (or link template) is
        interesting to a machine based client.

        I don't know what the convention is, but links can and do provide URLs
        for their description. That description URL, is, IMO the appropriate
        place for "form" metadata.

        Well, at least, that is my theory on how things might or should work....


        --
        Bill Burke
        JBoss, a division of Red Hat
        http://bill.burkecentral.com
      • Solomon Duskis
        Sure, HTML forms are usually entered by a human, but there s nothing inherently part of the elements that I selected that requires human intervention. I
        Message 3 of 22 , Oct 2, 2009
        • 0 Attachment
          Sure, HTML forms are usually entered by a human, but there's nothing inherently part of the <form> elements that I selected that requires human intervention. I do concede that HTML elements include "checkbox" and "radiobutton", but those don't have to be used in a <form> element meant for machine usage.  It wouldn't be all that difficult to come up with a set of <form> elements that would be better suited for machine interactions 

          The main point in favor of HTML forms:
          • The server wants a specific ACTION (rather than a document relationship)
          • The server expects a specific HTTP METHOD (rather than using out of band information to guess the method)
          • The server gives a NAME for the action (rather than a relationship type for the action)
          • The server gives a DETAILED BREAKDOWN of what it expects, potentially including constraints

          The main detractions of <link> + "rel":
          • ATOM's <link> generally indicates a relationship between documents.  rest-discuss has tried to overcome quite a few issues related to ACTIONS.
          • rel stands for relationship, right?  "rel" would have to define how a universal ACTION like CustomersByZip relates to the current document, not what the action is
          I'm not going to give up on this issue.

          -Solomon

          On Fri, Oct 2, 2009 at 9:48 AM, Bill Burke <bburke@...> wrote:


          Solomon Duskis wrote:
          Using link doesn't seem all that natural to me.  In HTML that question is answered pretty simply:

          <form action="http://example.com/customers <http://example.com/customers?zip=>" method="GET" name="CustomersByZip">

            <input type="text" name="zip" />
          </form>


          I've said this before when you posted this idea...But...

          <form> is rendering metadata meant to help a *Human Being* make a decision.  Machine based clients are already going to know how to fill out the "form" ahead of time so the rendering information isn't needed when transmitting representations.  Only the link (or link template) is interesting to a machine based client.

          I don't know what the convention is, but links can and do provide URLs for their description.  That description URL, is, IMO the appropriate place for "form" metadata.

          Well, at least, that is my theory on how things might or should work....



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

        • Bill Burke
          I m not sure you understood my point. My point was not to say URI templates are better than forms. My point was that transmitting a form (quotes) is usually
          Message 4 of 22 , Oct 2, 2009
          • 0 Attachment
            I'm not sure you understood my point. My point was not to say URI
            templates are better than forms.

            My point was that transmitting a "form" (quotes) is usually not useful
            to a machine-based client as the "discovery" phase happened when the
            programmer coded the client.

            Personally, I don't like the <link> or Link header format. IMO it
            should be something like:

            <link name="..." description="http:/..." href="http://..." type=""/>

            With description being an explicit URL. The client could ask for a
            specific rendering media type. In the current format (correct me if I'm
            wrong) it seems like the "rel" attribute is overloaded.

            Solomon Duskis wrote:
            > Sure, HTML forms are usually entered by a human, but there's nothing
            > inherently part of the <form> elements that I selected that requires
            > human intervention. I do concede that HTML elements include "checkbox"
            > and "radiobutton", but those don't have to be used in a <form> element
            > meant for machine usage. It wouldn't be all that difficult to come up
            > with a set of <form> elements that would be better suited for machine
            > interactions
            >
            > The main point in favor of HTML forms:
            >
            > * The server wants a specific ACTION (rather than a document
            > relationship)
            > * The server expects a specific HTTP METHOD (rather than using out
            > of band information to guess the method)
            > * The server gives a NAME for the action (rather than a relationship
            > type for the action)
            > * The server gives a DETAILED BREAKDOWN of what it expects,
            > potentially including constraints
            >
            >
            > The main detractions of <link> + "rel":
            >
            > * ATOM's <link> generally indicates a relationship between
            > documents. rest-discuss has tried to overcome quite a few issues
            > related to ACTIONS.
            > * rel stands for relationship, right? "rel" would have to define
            > how a universal ACTION like CustomersByZip relates to the current
            > document, not what the action is
            >
            > I'm not going to give up on this issue.
            >
            > -Solomon
            >
            > On Fri, Oct 2, 2009 at 9:48 AM, Bill Burke <bburke@...
            > <mailto:bburke@...>> wrote:
            >
            >
            >
            > Solomon Duskis wrote:
            >
            > Using link doesn't seem all that natural to me. In HTML that
            > question is answered pretty simply:
            >
            > <form action="http://example.com/customers
            > <http://example.com/customers?zip=>" method="GET"
            > name="CustomersByZip">
            >
            > <input type="text" name="zip" />
            > </form>
            >
            >
            > I've said this before when you posted this idea...But...
            >
            > <form> is rendering metadata meant to help a *Human Being* make a
            > decision. Machine based clients are already going to know how to
            > fill out the "form" ahead of time so the rendering information isn't
            > needed when transmitting representations. Only the link (or link
            > template) is interesting to a machine based client.
            >
            > I don't know what the convention is, but links can and do provide
            > URLs for their description. That description URL, is, IMO the
            > appropriate place for "form" metadata.
            >
            > Well, at least, that is my theory on how things might or should work....
            >
            >
            >
            > --
            > Bill Burke
            > JBoss, a division of Red Hat
            > http://bill.burkecentral.com
            >
            >

            --
            Bill Burke
            JBoss, a division of Red Hat
            http://bill.burkecentral.com
          • Solomon Duskis
            So are you suggesting that should be used because of out of band information found during the development phase? -Solomon
            Message 5 of 22 , Oct 2, 2009
            • 0 Attachment
              So are you suggesting that <links> should be used because of "out of band" information found during the development phase?

              -Solomon

              On Fri, Oct 2, 2009 at 10:11 AM, Bill Burke <bburke@...> wrote:
              I'm not sure you understood my point.  My point was not to say URI templates are better than forms.

              My point was that transmitting a "form" (quotes) is usually not useful to a machine-based client as the "discovery" phase happened when the programmer coded the client.

              Personally, I don't like the <link> or Link header format.  IMO it should be something like:

              <link name="..." description="http:/..." href="http://..." type=""/>

              With description being an explicit URL.  The client could ask for a specific rendering media type.  In the current format (correct me if I'm wrong)  it seems like the "rel" attribute is overloaded.

              Solomon Duskis wrote:
              Sure, HTML forms are usually entered by a human, but there's nothing inherently part of the <form> elements that I selected that requires human intervention. I do concede that HTML elements include "checkbox" and "radiobutton", but those don't have to be used in a <form> element meant for machine usage.  It wouldn't be all that difficult to come up with a set of <form> elements that would be better suited for machine interactions
              The main point in favor of HTML forms:

                 * The server wants a specific ACTION (rather than a document
                   relationship)
                 * The server expects a specific HTTP METHOD (rather than using out
                   of band information to guess the method)
                 * The server gives a NAME for the action (rather than a relationship
                   type for the action)
                 * The server gives a DETAILED BREAKDOWN of what it expects,
                   potentially including constraints


              The main detractions of <link> + "rel":

                 * ATOM's <link> generally indicates a relationship between
                   documents.  rest-discuss has tried to overcome quite a few issues
                   related to ACTIONS.
                 * rel stands for relationship, right?  "rel" would have to define
                   how a universal ACTION like CustomersByZip relates to the current
                   document, not what the action is

              I'm not going to give up on this issue.

              -Solomon

              On Fri, Oct 2, 2009 at 9:48 AM, Bill Burke <bburke@... <mailto:bburke@...>> wrote:



                 Solomon Duskis wrote:

                     Using link doesn't seem all that natural to me.  In HTML that
                     question is answered pretty simply:

                     <form action="http://example.com/customers
                     <http://example.com/customers?zip=>" method="GET"
                     name="CustomersByZip">

                       <input type="text" name="zip" />
                     </form>


                 I've said this before when you posted this idea...But...

                 <form> is rendering metadata meant to help a *Human Being* make a
                 decision.  Machine based clients are already going to know how to
                 fill out the "form" ahead of time so the rendering information isn't
                 needed when transmitting representations.  Only the link (or link
                 template) is interesting to a machine based client.

                 I don't know what the convention is, but links can and do provide
                 URLs for their description.  That description URL, is, IMO the
                 appropriate place for "form" metadata.

                 Well, at least, that is my theory on how things might or should work....



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



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

            • Tim Williams
              ... What do you mean by overloaded ? It seems that s it used consistently for one purpose (to indicate the relationship between the current URI and another
              Message 6 of 22 , Oct 2, 2009
              • 0 Attachment
                On Fri, Oct 2, 2009 at 10:11 AM, Bill Burke <bburke@...> wrote:
                > I'm not sure you understood my point.  My point was not to say URI templates
                > are better than forms.
                >
                > My point was that transmitting a "form" (quotes) is usually not useful to a
                > machine-based client as the "discovery" phase happened when the programmer
                > coded the client.
                >
                > Personally, I don't like the <link> or Link header format.  IMO it should be
                > something like:
                >
                > <link name="..." description="http:/..." href="http://..." type=""/>
                >
                > With description being an explicit URL.  The client could ask for a specific
                > rendering media type.  In the current format (correct me if I'm wrong)  it
                > seems like the "rel" attribute is overloaded.

                What do you mean by "overloaded"? It seems that's it used
                consistently for one purpose (to indicate the relationship between the
                "current" URI and another URI) since inception. I think it's
                confusing only because they've been introduced through media types
                instead of some separate, independent, mechanism though. It seems
                important enough to me that link relations should be first-class
                "things" just like the media formats themselves.

                --tim
              • Bill Burke
                ... Yes, exactly. If a client needs form metadata, it will ask for it. From what I ve read on rest-discuss, the definition of the link relationship and the
                Message 7 of 22 , Oct 2, 2009
                • 0 Attachment
                  Solomon Duskis wrote:
                  > So are you suggesting that <links> should be used because of "out of
                  > band" information found during the development phase?
                  >

                  Yes, exactly. If a client needs form metadata, it will ask for it.
                  From what I've read on rest-discuss, the definition of the link
                  relationship and the media type together is supposed to tell the user
                  how to interact with the href. Am I right?

                  --
                  Bill Burke
                  JBoss, a division of Red Hat
                  http://bill.burkecentral.com
                • Solomon Duskis
                  I don t think that we re far off, but we can do better. Specifically, better in the sense that the media type should be more self descriptive relating to
                  Message 8 of 22 , Oct 2, 2009
                  • 0 Attachment
                    I don't think that we're far off, but we can do better.  Specifically, better in the sense that the media type should be more "self descriptive" relating to the run-time documentation of the server's communication expectations.

                    The REST constraints aim to create dynamic and serendipitous behavior.  IMHO, Slightly more inline communication information will be more effective in achieving those results.

                    -Solomon

                    On Fri, Oct 2, 2009 at 10:37 AM, Bill Burke <bburke@...> wrote:


                    Solomon Duskis wrote:
                    So are you suggesting that <links> should be used because of "out of band" information found during the development phase?


                    Yes, exactly.  If a client needs form metadata, it will ask for it. From what I've read on rest-discuss, the definition of the link relationship and the media type together is supposed to tell the user how to interact with the href.  Am I right?

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

                  • Bill Burke
                    ... NO, I mean I ve see others do this: I mix of name and url in one string for the rel attribute. -- Bill Burke JBoss,
                    Message 9 of 22 , Oct 2, 2009
                    • 0 Attachment
                      Tim Williams wrote:
                      > On Fri, Oct 2, 2009 at 10:11 AM, Bill Burke <bburke@...> wrote:
                      >> I'm not sure you understood my point. My point was not to say URI templates
                      >> are better than forms.
                      >>
                      >> My point was that transmitting a "form" (quotes) is usually not useful to a
                      >> machine-based client as the "discovery" phase happened when the programmer
                      >> coded the client.
                      >>
                      >> Personally, I don't like the <link> or Link header format. IMO it should be
                      >> something like:
                      >>
                      >> <link name="..." description="http:/..." href="http://..." type=""/>
                      >>
                      >> With description being an explicit URL. The client could ask for a specific
                      >> rendering media type. In the current format (correct me if I'm wrong) it
                      >> seems like the "rel" attribute is overloaded.
                      >
                      > What do you mean by "overloaded"? It seems that's it used
                      > consistently for one purpose (to indicate the relationship between the
                      > "current" URI and another URI) since inception. I think it's
                      > confusing only because they've been introduced through media types
                      > instead of some separate, independent, mechanism though. It seems
                      > important enough to me that link relations should be first-class
                      > "things" just like the media formats themselves.
                      >

                      NO, I mean I've see others do this:

                      <link rel="foo http://blah.com/..."/>

                      I mix of name and url in one string for the "rel" attribute.


                      --
                      Bill Burke
                      JBoss, a division of Red Hat
                      http://bill.burkecentral.com
                    • Subbu Allamaraju
                      ... Not so. As [1] tries to define, a link relation type identifies the *semantics* of a link . A well-specified link relation will have to specify everything
                      Message 10 of 22 , Oct 2, 2009
                      • 0 Attachment
                        On Oct 2, 2009, at 4:02 PM, Solomon Duskis wrote:

                        > • rel stands for relationship, right? "rel" would have to define
                        > how a universal ACTION like CustomersByZiprelates to the current
                        > document, not what the action is
                        >

                        Not so. As [1] tries to define, "a link relation type identifies the
                        *semantics* of a link". A well-specified link relation will have to
                        specify everything about the link. For application specific relations
                        (as opposed to general purpose ones like "next" and "prev"),
                        specifying semantics is even more important. In the absence of such
                        semantics, links become meaningless.

                        Subbu

                        [1] http://tools.ietf.org/html/draft-nottingham-http-link-header
                      • Sam Johnston
                        2009/10/2 Subbu Allamaraju ... For application specific relations it s best to use URI relations (e.g. rel= http://pubsubhubbub.org/ ) as
                        Message 11 of 22 , Oct 2, 2009
                        • 0 Attachment
                          2009/10/2 Subbu Allamaraju <subbu@...>

                          On Oct 2, 2009, at 4:02 PM, Solomon Duskis wrote:

                          >       • rel stands for relationship, right?  "rel" would have to define
                          > how a universal ACTION like CustomersByZiprelates to the current
                          > document, not what the action is

                          Not so. As [1] tries to define, "a link relation type identifies the
                          *semantics* of a link". A well-specified link relation will have to
                          specify everything about the link. For application specific relations
                          (as opposed to general purpose ones like "next" and "prev"),
                          specifying semantics is even more important. In the absence of such
                          semantics, links become meaningless.

                          For "application specific relations" it's best to use URI relations (e.g. rel="http://pubsubhubbub.org/") as you then "own" the relation and can lock it down to certain protocols, content types, etc.

                          Registered relations (the Web Linking draft creates a new common IANA registry) should only be used where they are "broadly useful", such as for "first", "last", "related", "alternate". Accordingly registering "hub" for PubSubHubbub is looking like being rejected because it doesn't help and could actually hurt interoperability (what's a client to do if it encounters "hub" but both rssCloud and PubSubHubbub are using it?).

                          As content types aren't really useful for describing protocols it really doesn't make much sense to try to use it with the relation type as a "compound key" of sorts for identification purposes.

                          Sam
                           
                        • Subbu Allamaraju
                          Yes, as Sec 4.2 describes.
                          Message 12 of 22 , Oct 3, 2009
                          • 0 Attachment
                            Yes, as Sec 4.2 describes.

                            On Oct 2, 2009, at 11:06 PM, Sam Johnston wrote:

                            > 2009/10/2 Subbu Allamaraju <subbu@...>
                            >
                            > On Oct 2, 2009, at 4:02 PM, Solomon Duskis wrote:
                            >
                            > > • rel stands for relationship, right? "rel" would have to
                            > define
                            > > how a universal ACTION like CustomersByZiprelates to the current
                            > > document, not what the action is
                            >
                            > Not so. As [1] tries to define, "a link relation type identifies the
                            > *semantics* of a link". A well-specified link relation will have to
                            > specify everything about the link. For application specific relations
                            > (as opposed to general purpose ones like "next" and "prev"),
                            > specifying semantics is even more important. In the absence of such
                            > semantics, links become meaningless.
                            >
                            > For "application specific relations" it's best to use URI relations
                            > (e.g. rel="http://pubsubhubbub.org/") as you then "own" the relation
                            > and can lock it down to certain protocols, content types, etc.
                            >
                            > Registered relations (the Web Linking draft creates a new common
                            > IANA registry) should only be used where they are "broadly useful",
                            > such as for "first", "last", "related", "alternate". Accordingly
                            > registering "hub" for PubSubHubbub is looking like being rejected
                            > because it doesn't help and could actually hurt interoperability
                            > (what's a client to do if it encounters "hub" but both rssCloud and
                            > PubSubHubbub are using it?).
                            >
                            > As content types aren't really useful for describing protocols it
                            > really doesn't make much sense to try to use it with the relation
                            > type as a "compound key" of sorts for identification purposes.
                            >
                            > Sam
                            >
                          • wahbedahbe
                            Well, that doesn t mean that a form-like-thing couldn t work for machine driven clients. I know I keep saying this on this list but: take a look at CCXML! -
                            Message 13 of 22 , Oct 3, 2009
                            • 0 Attachment
                              Well, that doesn't mean that a "form-like-thing" couldn't work for machine driven clients.

                              I know I keep saying this on this list but: take a look at CCXML!
                              - It manages to implement form-like requests but is not driven by human input. It implements a state machine construct that is driven by events from an underlying platform. On each transisiton it can run javascript and send messages back down to the platform. It can also put together a GET or a POST using javascript variables to set the equivalent of form inputs.

                              This sort of model could work for more than just call control (what CCXML is designed for). Hypermedia tells the client how to map inputs to an HTTP request -- that basic concept is the same in HTML and CCXML.

                              Andrew

                              --- In rest-discuss@yahoogroups.com, Bill Burke <bburke@...> wrote:
                              >
                              >
                              >
                              > Solomon Duskis wrote:
                              > > Using link doesn't seem all that natural to me. In HTML that question
                              > > is answered pretty simply:
                              > >
                              > > <form action="http://example.com/customers
                              > > <http://example.com/customers?zip=>" method="GET" name="CustomersByZip">
                              > > <input type="text" name="zip" />
                              > > </form>
                              > >
                              >
                              > I've said this before when you posted this idea...But...
                              >
                              > <form> is rendering metadata meant to help a *Human Being* make a
                              > decision. Machine based clients are already going to know how to fill
                              > out the "form" ahead of time so the rendering information isn't needed
                              > when transmitting representations. Only the link (or link template) is
                              > interesting to a machine based client.
                              >
                              > I don't know what the convention is, but links can and do provide URLs
                              > for their description. That description URL, is, IMO the appropriate
                              > place for "form" metadata.
                              >
                              > Well, at least, that is my theory on how things might or should work....
                              >
                              >
                              > --
                              > Bill Burke
                              > JBoss, a division of Red Hat
                              > http://bill.burkecentral.com
                              >
                            • Bill Burke
                              ... I wasn t saying it was good or bad or needed or not needed. I was just saying that self description metadata isn t going to be used by a large set of
                              Message 14 of 22 , Oct 3, 2009
                              • 0 Attachment
                                wahbedahbe wrote:
                                >
                                >
                                > Well, that doesn't mean that a "form-like-thing" couldn't work for
                                > machine driven clients.
                                >

                                I wasn't saying it was good or bad or needed or not needed. I was just
                                saying that "self description" metadata isn't going to be used by a
                                large set of clients.

                                --
                                Bill Burke
                                JBoss, a division of Red Hat
                                http://bill.burkecentral.com
                              • wahbedahbe
                                ... I would argue that if a client doesn t need this metadata then it s not a RESTful system. This would imply that the client was too closely bound to the
                                Message 15 of 22 , Oct 3, 2009
                                • 0 Attachment
                                  --- In rest-discuss@yahoogroups.com, Bill Burke <bburke@...> wrote:
                                  > wahbedahbe wrote:
                                  > >
                                  > > Well, that doesn't mean that a "form-like-thing" couldn't work for
                                  > > machine driven clients.
                                  > >
                                  >
                                  > I wasn't saying it was good or bad or needed or not needed. I was just
                                  > saying that "self description" metadata isn't going to be used by a
                                  > large set of clients.
                                  >

                                  I would argue that if a client doesn't need this "metadata" then it's not a RESTful system. This would imply that the client was too closely bound to the URI structure of the server and/or server-specific data types. Some sort of metadata about the link (if its not a straight GET/PUT/DELETE of the verbatim link) is necessary to map information from the client's domain to the server's interface.

                                  Specifically, on your point earlier in the thread:

                                  >My point was that transmitting a "form" (quotes) is usually not useful
                                  >to a machine-based client as the "discovery" phase happened when the
                                  >programmer coded the client.

                                  This goes against the principles of REST. There is no service discovery phase that occurs during coding. The client is coded against the uniform interface. e.g. URI + HTTP + Hypermedia Format (+ Link Relations). A web browser works with any HTTP server that serves back HTML. A CCXML client (again, which is machine driven) works with any HTTP server that serves back CCXML -- the server could be implementing a conferencing service, or a service to locate the callee on multiple phones, or whatever. The CCXML client doesn't care, it just executes the CCXML, just as a web browser just executes the HTML.

                                  There's no "server-specific form types" in the uniform interface, or it wouldn't be uniform. The hypermedia format is not specific to a service. If anything, it's specific to a type of client. HTML is specific to (primarily visual) data presentation & interaction clients. VoiceXML is specific to aural data presentation & interaction clients. CCXML is specific to call control clients. Any of these hypermedia clients could interact with any number of services that return data in the client's hypermedia format. A single service, via conneg, can interact with various types of client. The client and server are not coupled to each other at all.

                                  IMO, the most common mistake is to design a format specifically for your service -- that's not RESTful as it always results in coupling. The trick is designing a hypermedia format for the client domain you wish to target (if no such format already exists -- if one exists, you should just use it). A client that is coded to work with that format is not bound to any one service.

                                  Regards,

                                  Andrew
                                • Solomon Duskis
                                  My main point in all of this is that HTML deserves a serious consideration. HTML does stand for HyperText Markup Language. While it does have a focus on UI
                                  Message 16 of 22 , Oct 6, 2009
                                  • 0 Attachment
                                    My main point in all of this is that HTML deserves a serious consideration.  HTML does stand for "HyperText Markup Language."  While it does have a focus on UI aspects, it has quite a few hypertext and semantic markup mechanisms.  

                                    IMHO, HTML deserves more consideration from the REST community.

                                    Regarding "rel" specifically, here's some of the relevant text from the URL you provided:

                                    4. Link Relation Types

                                    A link relation type identifies the semantics of a link. For example, a link with the relation type "copyright" indicates that the resource identified by the target IRI is a statement of the copyright terms applying to the current context IRI.
                                    ...
                                    they only describe how the current context is related to another resource.

                                    I'd like to point out two things:

                                    A) "rel" stands for relation, and is meant for semantics related to relationships.  It's called "Link Relation" for a reason.  Yes, there are semantics involved, but they appear to be constrained to semantics of relationships

                                    B) <link> used anywhere in the "body" (as opposed to html header) is contextual and relates one resource to another.  

                                    My question still remains: Is link/rel the right mechanism to express actions?  IMHO, it is worthwhile to at least consider alternatives to link/rel to express both global actions like 'search' and more "local" actions like 'cancel'/'payment'.

                                    -Solomon

                                    On Fri, Oct 2, 2009 at 4:09 PM, Subbu Allamaraju <subbu@...> wrote:

                                    On Oct 2, 2009, at 4:02 PM, Solomon Duskis wrote:

                                           • rel stands for relationship, right?  "rel" would have to define how a universal ACTION like CustomersByZiprelates to the current document, not what the action is


                                    Not so. As [1] tries to define, "a link relation type identifies the *semantics* of a link". A well-specified link relation will have to specify everything about the link. For application specific relations (as opposed to general purpose ones like "next" and "prev"), specifying semantics is even more important. In the absence of such semantics, links become meaningless.

                                    Subbu

                                    [1] http://tools.ietf.org/html/draft-nottingham-http-link-header

                                  • Jan Algermissen
                                    ... No. Hypermedia semantics tell (via the spec) the client what expectations it may have about the link target (contextual typing information). The actual
                                    Message 17 of 22 , Oct 6, 2009
                                    • 0 Attachment
                                      On Oct 6, 2009, at 1:50 PM, Solomon Duskis wrote:

                                      > My question still remains: Is link/rel the right mechanism to
                                      > express actions?

                                      No. Hypermedia semantics tell (via the spec) the client what
                                      expectations it
                                      may have about the link target (contextual typing information). The
                                      actual
                                      effect of an HTTP invocation is to be defined in the spec.

                                      For example: AtomPub defines what links/hypermedia you must find in
                                      responses to
                                      deduce that some resourse is an AtomPub collection[1]. Then AtomPub
                                      defines what
                                      is achieved by POSTing to the resource.

                                      Jan



                                      [1] It must appear in a service document as a <collection href="">
                                      element
                                    Your message has been successfully submitted and would be delivered to recipients shortly.