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

18819Re: [rest-discuss] Re: Rel attributes?

Expand Messages
  • mike amundsen
    May 5 3:39 AM
    • 0 Attachment
      note that neither option contains: http method or encoding information.

      that is "out of band" knowledge in these designs.

      is that "good" or "bad" here?

      mca
      http://amundsen.com/blog/
      http://twitter.com@mamund
      http://mamund.com/foaf.rdf#me



      On Sat, May 5, 2012 at 6:26 AM, Rushforth, Peter
      <peter.rushforth@...> wrote:
      > Hi Mike,
      >
      > A couple of my replies through the yahoo web interface have gone awol.
      >
      > Thanks for this.
      >
      > Both rely on the hypermedia documentation, per Roy's hypermedia-apis-must-be-hypertext-driven post.
      > The first option is simpler, so it gets my vote, in the absence of a defined use for the extra markup.
      >
      > Cheers,
      > Peter
      > ________________________________________
      > From: mca@... [mca@...] on behalf of mike amundsen [mamund@...]
      > Sent: May 5, 2012 1:04 AM
      > To: Jørn Wildt
      > Cc: paul_k_moore; Rushforth, Peter; rest-discuss@yahoogroups.com
      > Subject: Re: [rest-discuss] Re: Rel attributes?
      >
      > Jørn, Paul, Peter:
      >
      > here are two options for a hypermedia affordances in a media type
      > design that supports writing new and updating existing resources:
      >
      > <create href="..." >...</create>
      > <update href="...">...</update>
      > OR
      > <write href="..." action="create">...</write>
      > <write href="..." action="update">...</write>
      >
      > Which relies on more "out-of-band" knowledge?
      > Which is a "better" design and why?
      >
      > mca
      > http://amundsen.com/blog/
      > http://twitter.com@mamund
      > http://mamund.com/foaf.rdf#me
      >
      >
      >
      > On Fri, May 4, 2012 at 4:45 PM, Jørn Wildt <jw@...> wrote:
      >>> > It is not good if you use rel to denote other information,
      >>> > like saying rel="CreateWithPost" to hint the agent to
      >>> > use the link's URI with a POST to create something.
      >>> > That is not the intended use and it is a bad practice.
      >>
      >>> It seems reasonable to me, I don't see why it is a bad practice.
      >>> It looks a lot like the atom:link@rel="edit", or html's @method="POST".
      >>
      >> I would say that you can do rel="CreateWithPost" and declare that in the
      >> link-rel documentation. But you loose something by doing so: allowing the
      >> server to specify HTTP method and payload encoding at runtime (since that
      >> knowledge would have to be a hardcoded part of the link-rel knowledge).
      >>
      >> Had the link "Create" instead lead to a form of some kind then the form
      >> could specifiy HTTP method at runtime, thus letting the server evolve over
      >> time (changing HTTP method) without updating the clients (as they are
      >> expected to understand the full form language).
      >>
      >> I haved tried to illustrate this in
      >> https://groups.google.com/d/msg/hypermedia-web/mtdVPRks_QI/ZEK3_9QBVtoJ -
      >> check the "evolving server, stable client" scenarios in example 1, 2 and 3.
      >>
      >> /Jørn
      >>
      >> ----- Original Message -----
      >> From: Rushforth, Peter
      >> To: paul_k_moore
      >> Cc: rest-discuss@yahoogroups.com
      >> Sent: Friday, May 04, 2012 2:28 PM
      >> Subject: RE: [rest-discuss] Re: Rel attributes?
      >>
      >>
      >>
      >> Hi Paul,
      >>
      >> In atompub, the rel="edit" link relation means you can PUT or DELETE to the
      >> href.
      >>
      >> Also in atompub, app:collection/accept/text() tells you you can POST the
      >> app:collection/@href whatever MIME types are
      >> listed in the app:accept text().
      >>
      >> Going by that as an exemplar, it seems to me that it is the hypermedia
      >> format which is defining what can and can't be
      >> done against the URL.  Maybe that is out of band knowledge, but then again,
      >> knowing what @method="POST" means
      >> could be considered out of band too.   It has to be written down somewhere
      >> and agreed to.  So the sharing of the semantics
      >> widely is key to interoperability.  Hence a public link relations registry.
      >> It is the shared semantics that allows us to
      >> program user agents to do predictable things when they come across a
      >> particular hypermedia construct.
      >>
      >> Maybe it is important that when a GET is done on a resource, that the
      >> response metadata also declare the available methods.
      >> Message metadata is authoritative.
      >>
      >> But you should not have to do that GET, because it is a waste of bandwidth,
      >> and the representation format has already
      >> defined (in the registry) and declared (in the instance in which you find
      >> the href) the (possibly implicit) method availabilities.
      >>
      >>> 3. It is important to understand that the rel is the relation the resource
      >>> identified by the link's URI, has with the actual resource/uri/document.
      >>> It is not good if you use rel to denote other information, like saying
      >>> rel="CreateWithPost" to hint the agent to use the link's URI with a POST
      >>> to create something. That is not the intended use and it is a bad
      >>> practice.
      >>
      >> It seems reasonable to me, I don't see why it is a bad practice.  It looks a
      >> lot like the atom:link@rel="edit", or html's @method="POST".
      >>
      >> Cheers,
      >> Peter
      >>
      >>
      >>
      >>
      >>
      >> From: rest-discuss@yahoogroups.com [mailto:rest-discuss@yahoogroups.com] On
      >> Behalf Of paul_k_moore
      >> Sent: May 3, 2012 11:00
      >> To: rest-discuss@yahoogroups.com
      >> Subject: [rest-discuss] Re: Rel attributes?
      >>
      >>
      >>
      >>
      >>
      >> William
      >>
      >> This is very useful - thank you.
      >>
      >> Just to confirm my (refined) understanding here, I consider the meaning of
      >> 'rel' to be an orthogonal concern to the HTTP methods.
      >>
      >> To expound slightly, I had erroneously conflated the HTTP methods (avaialble
      >> at the target URI) into the meaning of 'rel'. If we consider the following
      >> two examples:
      >>
      >> Example 1: Use of a 'rel' such as 'http://relations.example.com/order'
      >> reasonably conveys to the user-agent that there is something 'order'-like at
      >> the target URI. It is then up to the client (the client intent) to follow
      >> this rel (using an implicit GET request) to retrieve the representation of
      >> the 'order'-like thing (as rendered in a specific media-type).
      >>
      >> Example 2: Use of a 'rel' such as 'http://relations.example.com/new' to
      >> (unreasonably) convey that the user agent can POST an item of the type
      >> communicated by it's current context. This is the problem, I don't need to
      >> 'say' to the user-agent that it can POST at a specific URI, because the
      >> available HTTP methods tell me what I can do with the resource. What I need
      >> to do is examine the permitted methods (either by inspection of the 'Allow'
      >> header, or an OPTIONS request) AND not try to convey the permutations of
      >> method in the 'rel'.
      >>
      >> Does that make sense?
      >>
      >> Thanks in advance
      >>
      >> Paul
      >>
      >> --- In rest-discuss@yahoogroups.com, "William Martinez Pomares"
      >> <wmartinez@...> wrote:
      >>>
      >>> Hi nikonguy74!
      >>> Just to complement what Jan is saying:
      >>> 1. Links represent resources you can work with. The idea of links is that
      >>> you can usually follow them (issuing a GET operation), but then there are
      >>> lots of questions you may have about them: what do I do with the actual
      >>> resource (say, web page) I'm in? What is this link referring to? What
      >>> other operations apart from GET can I execute with it? Can I add query
      >>> parameters to it? What media type will it return? What media type may it
      >>> expect if I can issue a POST?, etc...
      >>>
      >>> 2. rel is an attribute to add more information about a link. I denotes a
      >>> value, keyword, hint of what relation the link has with the current
      >>> resource/IRI. Say you are in a book page, that is your current resources
      >>> and it has a URI. A link with rel="next" will hint that following that
      >>> link will get you to the next page of the book.
      >>>
      >>> 3. It is important to understand that the rel is the relation the resource
      >>> identified by the link's URI, has with the actual resource/uri/document.
      >>> It is not good if you use rel to denote other information, like saying
      >>> rel="CreateWithPost" to hint the agent to use the link's URI with a POST
      >>> to create something. That is not the intended use and it is a bad
      >>> practice.
      >>>
      >>> 4. You may need actual business intelligence in your client. If you are
      >>> looking at a blog comment, a rel="parent" will tell you the links points
      >>> to the actual blog post. Having that information, you can start asking
      >>> that parent for information, or even send a comment to it using POST
      >>> operation. That is natural simply because much of this interaction is
      >>> already designed in the specs, and the agent may not need to be statically
      >>> programmed, but it will need intelligence.
      >>>
      >>> 5. So, you have there standard metainformation (like how to handle media
      >>> types, the semantics of POST and PUT, the semantics or link and rel), etc.
      >>> Plus, you have business specific semantics (the actual value of the rel
      >>> may mean something applicable only to, say, banking applications). With
      >>> that info you can program intelligent clients.
      >>>
      >>> 6. Finally, some other "link" tags like anchor and image are special links
      >>> that have a standard meaning and established processing. If you found an
      >>> <img> tag you automatically know that link is referring to an image, and
      >>> if you are in HTML page in a browser, the supposed processing it to fetch
      >>> that image with a GET and display it based on context and additional
      >>> attributes. All that is told by the tag name, and everybody in the world
      >>> knows it. So, links are difficult to understand at first but once you have
      >>> it clear they are simple to use. Only don't expect the link rel attribute
      >>> will tell you everything.
      >>>
      >>> Cheers
      >>>
      >>> William Martinez.
      >>> --- In rest-discuss@yahoogroups.com, Jan Algermissen <jan.algermissen@>
      >>> wrote:
      >>> >
      >>> >
      >>> > On Mar 19, 2012, at 6:40 PM, nikonguy74 wrote:
      >>> > >
      >>> > > I know one of the first questions i had was on rel link. I understand
      >>> > > the basic premise behind rel attributes(to provide a general
      >>> > > documentation for how to interact with the link provider).
      >>> >
      >>> > The premise of the rel attribute on links is (in the case of the HTML or
      >>> > Atom media types) to provide information about the meaning of the link
      >>> > beyond 'this is a link'. If you register your rel name in the IANA
      >>> > registry, you can use the short name you registered, e.g. 'next' or
      >>> > 'up'. If you did not register your rel, you need to provide a URI.
      >>> > Simply for the matter of making your rel unambiguous.
      >>> >
      >>> > If that URI points to a human readable page explaining the relation,
      >>> > then that is even better.
      >>> >
      >>> > There is no magic (not even in REST :-) that removes the need to
      >>> > implement in code (or configure) what the user agent should do when it
      >>> > sees your link rel value.
      >>> >
      >>> > <link rel="http://foo/customerDetails" ... /> is conceptually the same
      >>> > as <link rel="working-copy" .../> and also as HTML's <img src="..."/> or
      >>> > AtomPub's <collection href="..."/>. It is just hypermedia ... that a
      >>> > user agent needs to be programmed to do something with ... in order to
      >>> > have it do something with it.
      >>> >
      >>> > IOW, your browser downloads that image because it is programmed to do
      >>> > so. This same concept also applies to other hypermedia - your user agent
      >>> > component will act on the hypermedia it comes across in the way it is
      >>> > programmed (or configured) to do.
      >>> >
      >>> > No magic.
      >>> >
      >>> > The effect of the hypermedia constraint is actually more felt in the
      >>> > obligations you have as a client side programmer (to react to the
      >>> > hypermedia you actually come across instead of the one you presume to
      >>> > come across) than it is felt in the aspect of loose coupling.
      >>> >
      >>> > REST mostly makes explicit that there isn't any control over the server
      >>> > side in networked systems. REST encourages you to deal with that rather
      >>> > than magically solves a problem that cannot be solved. And on top of
      >>> > that, REST provides a number of mechanism that optimize for *dealing
      >>> > with* the problem (e.g. content negotiation).
      >>> >
      >>> > HTH,
      >>> >
      >>> > Jan
      >>> >
      >>> > > The question is what would you see if you go to the rel link? Is it
      >>> > > something a person is suppose to interact with (say to get
      >>> > > documentation for new links added to a specific response) or something
      >>> > > code can interact with to determine what it needs to do? Unfortunately
      >>> > > in the book they don't give an example of what a "rel" page would look
      >>> > > like. For example the link:
      >>> > > <link rel="http://relations.restbucks.com/payment"
      >>> > > href:="http://restbucks.com/payment/1234" />
      >>> > >
      >>> > > If you typed in "http://relations.restbucks.com/payment" into your web
      >>> > > browser what would you see?
      >>> > >
      >>> > > thanks...
      >>> > >
      >>> > >
      >>> >
      >>>
      >>
      >>
      >>
      >>
      >>
      >>
      >> ------------------------------------
      >>
      >> Yahoo! Groups Links
      >>
      >>
      >>
      >
      >
      > ------------------------------------
      >
      > Yahoo! Groups Links
      >
      >
      >
    • Show all 23 messages in this topic