Add Resource#rel, links and embeds are implementation details

[bkeepers]

From what I understand of HAL and hypermedia, links and embeds are implementation details that the consumer should not know about. relations are what matter.

section 8.3 of the HAL draft:

The "hypertext cache pattern" allows servers to use embedded resources to dynamically reduce the number of requests a client makes, improving the efficiency and performance of the application. Clients MAY be automated for this purpose so that, for any given link relation, they will read from an embedded resource (if present) in preference to traversing a link.

To activate this client behaviour for a given link, servers SHOULD add an embedded resource into the representation with the same relation.

So I propose that the following changes be made to Hyperclient.

• Add a #rel method to Resource that first looks for an embedded resource and then a link.
• Add #[] and #method_missing on Resource that delegates to #rel
• Update all the docs to encourage the use #rel instead of #links and #embedded

[rehevkor5]

Hi @bkeepers thanks for commenting on my Issue. I agree with your approach except for delegating [] and method_missing to #rel. For one thing, it would allow collisions if there are attributes called 'attributes', 'links', 'embedded', or 'rel' (as bad of a modeling idea as that might be, I still think collisions should be avoided). Also, I like the separation that Hyperclient maintains between the attributes of the resource itself, the links, and the embedded objects. Your proposal just adds another to that list... I think it's better left up to the individual user if they want to transparently skip over the call to #rel.

[bkeepers]

Ok, that's fair.

One thing I started thinking today that would love your thoughts on: Attributes, links and embeds are all wrapped in a collection object, would it make sense for #rel to return a similar object? That would allow resource.rel[:thing] or resource.rel.thing.

[oriolgual]

I agree with @rehevkor5 here, and I really like the idea of using rel. I'm not following you in your last comment, right now rel would return either a Resource or a Link. What are you actually suggesting?

[bkeepers]

I'm suggesting #rel should return a Collection-like object that proxies both links and embedded resources. That would give it a more consistent interface with the rest of hyperclient.

[txus]

@bkeepers: is it possible for a call like rel[:foo] to return one link and one embedded object that both have the name :foo? How would the collection-like API deal with that?

[bkeepers]

My understanding is that rels should uniquely identify resources. So if there's an embedded resource and a link with the same name, they should both represent the same resource. I would expect the client to favor the embedded resource to avoid unnecessary network calls.

[txus]

@bkeepers then I think it looks good, this collection-like API. What do you think @oriolgual ?

[oriolgual]

@bkeepers do you think this is mergeable or it needs more work?

[txus]

Closing until @bkeepers gets back to us.