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

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

Expand Messages
  • Paul Moore
    May 4, 2012

      Caveat: I am not an ATOM expert, happy to be corrected.

      I have investigated the 'edit' link relation previously and concluded that the semantics are confused.

      The definition from ATOMPUB is:

      "The value of "edit" specifies that the value of the href attribute is the IRI of an editable Member Entry. When appearing within an atom:entry, the href IRI can be used to retrieve, update, and delete the Resource represented by that Entry..."

      So, actually 'edit' means GET, PUT, DELETE (in at least one context :-).  We could have a conversation about what 'self' means (a restatement of GET?), but let's park that for a moment.

      Then latterly in the Spec there's this, which informs us that the member entry in a feed may not be complete. 

      "Clients MUST NOT assume that an Atom Entry returned in the Feed is a full representation of an Entry Resource and SHOULD perform a GET on the URI of the Member Entry before editing it."

      This is (at best) annoying for a user-agent which has to either (i) understand the completeness of the member entry in the feed - for which I see no mechanism to determine, or (ii) must always execute a GET, PUT cycle to make a change.  If a GET is required anyway, there are other standard mechanisms to inform the user-agent of the permitted methods (e.g. 'Allow' header).  I consider this part of the spec to somewhat of an over-constraint, and would rather 'edit' was defined as "an intent to do some editing".

      Additionally, the conflation of method with rel here gives rise to a considerable number of missing permutations of resource state transition i.e. what about resources I can GET & DELETE but not PUT (does 'edit' still apply?); GET & POST (nothing defined).  Anyway, you get my point I'm sure.


      I haven't investigated the app:collection/@href semantics - I'll take a look :-)

      I agree the semantics of 'rel' need to be documented in the media type - this is one of the reasons I think we need specific media types for (new) domain problems.  Today's 'special' link relations are the standards of tomorrow - after agreement.

      Additionally, the semantics of the link relation can (and do) change with the (current) context of the application, so these context based refinements of rel semantics also need to go in the media type.

      So, I'm still on the side that the method and rel should be orthogonal concerns, and that atompub's 'edit' does not help here.

      Best regards


      On 4 May 2012, at 13:28, Rushforth, Peter wrote:

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

      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?



      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


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

    • Show all 23 messages in this topic