link relationship (Mike can you explain)

[nickdu]

I happen to be reading a RAML related post on API Craft (https://groups.google.com/forum/#!topic/api-craft/zboTwcsfDus) and ran across this post from Mike Amundsen:

"indicating relationships between abstract resources is just one possible use of a link. links can also be a part of explicit affordances. 

using the characters e-d-i-t to indicate a relationship is a bad idea.

however, annotating a link with the characters e-d-i-t is not an "anti-pattern", it is another use of links."

Darrel then commented:

"Mike,

On Wed, Jul 16, 2014 at 1:44 PM, mca <m...@amundsen.com> wrote:
> pretty sure the first sentence is not a problem since it echoes your comment
> to Jorn. i suspect you refer to the second sentence as the problem. the word
> "annotation" for me includes more then just the "rel" value. i do not find
> it an "anti-pattern" to indicate the use of a link with strings like "add"
> or "new". i *do* find it a bad idea to use the "rel" property (as defined in
> HTML) for this.

This was a light-bulb moment for me.  I believe I finally see the
disconnect that has existed between our perspectives.  I just chose a
different solution to the problem.  I like to refer to link relation
types as simply link types because the term relation is too
constraining in that it infers something very passive.  The word
"link" already communicates that there is a connection to another
resource.

The use of "rel" as the attribute to identify the link type is an
unfortunate historical artifact, but fairly insignificant.

Now I think I understand why you make the distinction between links
and forms, whereas I see it as unnecessary.

Darrel"

It seems like there might be a subtle but significant point here but I'm not getting it yet.  Can someone shed some light on it?  Examples maybe?  I can think of two examples:

HTML:

<a href="..." rel="edit">...</a>

HAL:

"_links": {
  "edit" : {"href" : "..."}
}

Are those both considered similar?

Thanks,
Nick

[Rick Cobb]

I would claim they're identical.

--
You received this message because you are subscribed to the Google Groups "Hypermedia Web" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hypermedia-we...@googlegroups.com.
To post to this group, send email to hyperme...@googlegroups.com.
Visit this group at http://groups.google.com/group/hypermedia-web.
For more options, visit https://groups.google.com/d/optout.

[mca]

what i was driving at in that snippet of the thread is that there is more than one way to decorate a link.

the @rel attribute was initially meant to indicate a "forward" relationship between the current resource and the one at the other end of the link. for example <link href="..." rel="father" /> says "if you follow this link, you'll find a resource that represents 'my' father." conversely there was intially a @rev attribute to indicate a "backward" relationship between resources. for example, the "father" resource i just mentioned by contain this: <link href="..." rel="daugher" /> which says "if you follow this link you'll find a resource that represents 'my' daughter."

the @rev has fallen out of use and is deprecated in HTML. forward and back become conflated and all are just now @rel.

however @rel is now also often used to contain other data than "relationship" for example, some Microformat registered values are really *actions* like "sub" and "unsub" for pubsub use, etc. 

and it is common for devs to simply use the @rel attribute as a stand-in for an RPC function name:

rel="update"

rel="delete"

rel="report"

rel="computeTax'

and so on...

so much so that, in the UBER design we'll likely be changing the @rel property to @role.

my point, again, is there are multiple uses for @rel. some relationship-driven, others operations-driven.

cheers.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[nickdu]

Thanks, I think I understand what you're saying now.  I want to follow up on this as bit.  Hopefully I won't have this going off in too many directions.  I think the additional questions I have are all related.

1. Do we need "action" type link relations?  It seems from your post I quoted and your reply you don't think actions should be used in the "rel" property of a link.  That seems reasonable enough.  Here's an example which I was thinking of using some form of an action link relation.

For an issuetracker service we wanted to call special attention to "closing an issue".  Closing an issue also has some side effects which is another reason we didn't want to expose a 'state' property which someone close simply set to 'closed'.  So the plan was to expose an issuestoclose collection.  To close an issue you would simply post the URL of the issue to this collection.  Hopefully that doesn't sound too bad so far.  The representation for an issue might want to include a link for closing an issue.  I'm thinking HAL right now so everything would be done via links and link relations.  It would seem in this case that we'd want a link relation with the word 'close' in it.

2. Not sure how well I'm going to word this one.  I read over the c+j spec and in the spec you define how to add, edit and delete items in a collection.  Since the spec defines that then it seems reasonable you don't need those hypermedia controls in the payload.  However, are such hypermedia controls needed in other hypermedia types which don't specifically spell that out?  For instance, let's say I'm using HAL and I have a collection, should the collection expose a link with a rel of "add"?  Or should it be assumed in all hypermedia types that POST'ing to a collection adds an item to the collection?  If we are to assume we can POST to add, then I of course need to know that my current representation is a collection.  I guess the rel of the link that got me to this representation might have indicated that.  Is that enough?  Same questions for delete, replace and update.

3. This is related to #2.  From http://www.imc.org/atom-protocol/mail-archive/msg03561.html:

Whatever happened to the idea that Atom was based on REST principles
of resources that have identifiers which a client could apply a
method to and see if that method worked by looking at the response?

Atom doesn't need rel="edit" or rel="editcontent" or app:edit-content.
All it needs is one identifier for the entry and an identifier for
each <content>.  Everything else can be determined by the client when
it accesses the server, assuming Atom has properly defined the meaning
of redirects.  If you have a desperate need to tell clients that they
should not try to edit a given resource, then add

Link: <other-URI>; rel="source"

to the header fields of the HTTP responses.  This is not Atom-specific
functionality.

....Roy

It seems like Roy is saying we should assume certain expected behavior.

3. From http://www.ebpml.org/blog/217.htm and http://www.tbray.org/ongoing/When/200x/2009/03/20/Rest-Casuistry they talk about actions.  I guess we can think of them as the stuff that at first glance when coming from a RPC interface doesn't seem to fit as a resource or a collection of resources.  I think one article I read said something to the affect: "if you find yourself wanting another HTTP method realize that what you need is another resource".  Therefore after you get done mapping these remaining actions to resources you're not left with any actions.  It would seem then that there is no need for an action-type link relation.  If we take the Tim Bray example, rebooting a VM would simply be POST'ing some payload to the 'vmstoreboot' collection.

Thanks,
Nick

[mca]

<snip>

1. Do we need "action" type link relations?  It seems from your post I quoted and your reply you don't think actions should be used in the "rel" property of a link.  That seems reasonable enough.  Here's an example which I was thinking of using some form of an action link relation.

</snip>

i think a better question (esp. in light of the Fielding quote you selected) is: "Are 'action' type indicators in responses useful?" and my reply is: "yes".  

@rel is not the only place to offer this (i gave the example from XLink of @role which UBER will likely be using). there are other ways to indicate available actions. debating *how* to indicate actions is not the same as debating "useful" or "needed", etc.

<snip>

 Since the spec defines that then it seems reasonable you don't need those hypermedia controls in the payload. 

</snip>

vague, but let me take a run at it.

1 - the CRUD implicit hypermedia in Cj (which mirrors Atom) indicates a general assumption on what actions are *possible* and, as fielding notes, clients are free to make attempts the watch results. What Atom format does not suppy (and what Cj *does* supply) is additional information on *how* these actions can be carried out. for example:

0 - items[].href is defined as a parameterless read-only navigation (to return a single item in the collection)

1 - the link[] items (both collection.links and items[].links) are defined as parameterless read-only navigations (@render="link")  or embedding (@render="image").

2 - the queries[] items are defined as parameterized read-only navigations (using data[] as the parameters w/ URL construction rules matching that of HTML.FORM@get).

3 - the template{} item is defined as a parameterized write navigations (using data[] as the body to pass to the service).

These four features are missing in Atom. while a client *could* take the "fielding" approach and simply supply random query-string and body parameters against likely methods to see the server's reactions, i think it "useful" to provide these details in the responses to cut down on the need for a client (and the client's human programmer) to experiment in oder to find what works.

The other links you provide all circle the same general topic -- assuming operations and arguments vs. claiming a particular use of the protocol is undesirable.my respons, in general to these kinds of discussions is: "meh."

by providing (in responses) machine-readable descriptions of available actions i have been able to:

- build client apps that "late-bind" on a)addresses, b)arguments, c)workflow

- reduce human-written documentation to support service provider APIs

- increase the number of feature changes that are possible w/o updating consumer apps.

- reduce the amount of breakage that occurs in interfaces when adding new features

yes, i like "action" type indicators.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

--

[nickdu]

If we don't make any assumptions on resources I guess that means for a resource that allows delete we should provide something like the following link/action:

delete : {"href" : "http://..."}

similarly for a collection resource which supports additions we should provide:

add : {"href" : "http://..."}

Thanks,
Nick

[come...@comcast.net]

The other links you provide all circle the same general topic -- assuming operations and arguments vs. claiming a particular use of the protocol is undesirable.my respons, in general to these kinds of discussions is: "meh."

Ahhhhhh! Well this helps sheds some light on me breaking my leg in a unexpected pothole on some of the protocol angled interactions we've had ;).
 

by providing (in responses) machine-readable descriptions of available actions i have been able to:

- build client apps that "late-bind" on a)addresses, b)arguments, c)workflow

- reduce human-written documentation to support service provider APIs

- increase the number of feature changes that are possible w/o updating consumer apps.

- reduce the amount of breakage that occurs in interfaces when adding new features

yes, i like "action" type indicators.

This is awesome. Actions seems like an important aspect that keeps popping up. I bumped against similar considerations when working on my own projects. Do we perceive that there is a need to distinguish relations from actions though? I know that we touched on that aspect as some point and you had mentioned then that sometimes "rel is all you have to work with". But is there a need to actually differentiate the two? Are we able to more clearly articulate certain M2M interactions by differentiating relations from actions?

Regards
Jeff Michaud