enable following embedded self-link when matching with secondary key

[travi]

When following a link and using a secondary key and value, it appears that the embedded resource is preferred rather than following the link in the embedded resource to request the full representation.

I am able to confirm this behavior both by a difference in attributes included in the embedded version of the resource and the full one as well as my integration tests. I use nock to stub api calls and the output for calls to the stub show that a call is never made for the resource itself. The chain stops after the list is requested.

I thought that my pull request for #8 covered this, but it appears that I did not pay close enough attention. This is still the behavior after the 2.0.1 release. Feel free to reference my sample api client and see the problem there, if that would be helpful. npm test will at least show the output from the calls to nock.

[basti1302]

I think there might be a misinterpretation of preferEmbedded here. A single hal document might contain the same key both in _links and in _embedded. Like this:

{
  _links: { 
    foo: {
      href: '/foo' 
    } 
  },
  _embedded: { 
    foo: {
      some: value  
    }
  }
}

The issue about preferring the embedded over the link or vice versa is wether to follow the link (that is, accessing /foo with an HTTP request) or just using the embedded foo doc with (the one, that has some: value).

That's how it is recommended in https://tools.ietf.org/html/draft-kelly-json-hal-06#section-8.3 (at least in my understanding). So if you want Traverson to follow the link, you need an actual link in the _links section. I cite: "Servers SHOULD NOT entirely "swap out" a link for an embedded
resource (or vice versa) because client support for this technique is
OPTIONAL."

The question is not whether a self-href from an embedded doc will be followed automatically. Currently Traverson will never do that by itself. One might discuss if that is a reasonable optional feature or not. Currently I'm not sure about that.

[basti1302]

Closing this one as it is not a bug. If you would like to turn it into a feature request, feel free to re-open.

[travi]

Sure, I understand what you are saying. However, I do think that using a secondary matcher makes following from _links extremely difficult since there are no attributes included to match against. I wouldn't want to turn the traversal into a need to follow each link in the collection under _links in order to find the proper match. If you would be open to making following the default behavior, could it be considered non-breaking to require the use of preferEmbeddedResources() to prevent following since the ability to match with secondary key was just added (there should be no coupling to the non-existent old behavior)?

I suppose the other option might be to use .getUrl() instead of .getResource() and make a separate request for that resource, but that seems less in line with the goals of following links through simple interaction with traversal. Please feel free to point out additional options if there is another way to approach this.

Also, my team actually just had a conversation about the part of the spec that you cited above because we are confused about that as well. We were leaning toward embeds replacing links until we found that. We think that approach makes sense for top level links, such as those on a single resource. It gets more complex when using that approach for collections. Plus we were struggling to find a use case where a collection of links would be valuable on their own because of some of the things that I mentioned above. We have, for now, landed on it not making sense to include links for collections that default to embedding the list of resources in the response.

[travi]

For a little more context, we plan to purposefully return partial resources in collections. We will embed enough information to provide reasonable summaries for displaying lists to a user and enabling them to choose. Mainly we plan to limit the included links at the collection level as calculating access to certain actions can be expensive.

As you mentioned in the readme: the spec says that an embedded resource may "be a full, partial, or inconsistent version of the representation served from the target URI", so to get the complete and up to date document your best bet is to follow the link to the actual resource, if available. We plan to set the expectation that links self links should be followed from a resource that is embedded, once it has been chosen.

Since the self link has already been returned when that interaction happens, we could theoretically follow that link directly as a result of the choice. However, that gets complex with clients that are stateless web applications as they would need to either url encode that uri and include it in the GET request from the browser or find a way to persist that uri in a way that it could be looked up with a simpler key.

Hope this info helps understand the situation.