Soft resource reference

[jirenius]

Issue

It should be possible to have "soft" resource references that Resgate won't automatically follow.

This would allow for breaking up large nested data structures into smaller parts, while keeping the references between them explicit.

Suggested solution

Extend RES Protocol - Resource reference with an optional "soft": true parameter, which marks the link as soft.

Example

{ "rid": "foo.model", "soft": true }

Resgate should not follow this link, but treat it as a simple value.

HTTP response

When the parent resource is fetched using HTTP, the reference should be presented as a href URL string:

Example HTTP response:

{
    "name": "Jane Doe",
    "profile": { "href": "/api/user/42/profile" } // Profile uses a soft link
}

ResClient (WS) response

The soft link should be turned into an object with a property, rid, returning the resource ID, and a method, get, which fetches the resource:

client.get('user.42').then(user => {
    console.log(user.name); // Jane Doe
    console.log(user.profile.rid); // user.42.profile
    user.profile.get() // Same as client.get('user.42.profile')
        .then(profile => (/* ... */));
});

Considerations

• By adding a field to the existing resource reference, older versions of Resgate would simply ignore the property and follow the links without breaking.
• The property is named "soft" instead of a more descriptive "nofollow" as the term soft reference is easier to use than a no-follow reference or a non-embedded reference.
• Using "soft": true as property (as oppose to "hard": false) does more obviously default to false when the property is missing.
• Subscribing to a soft referenced resource will use the same subscribe request as any other resource, which includes explicitly granting access through an access request.
• For clients connecting with older ResClient versions, the legacy behavior is that Resgate should return the soft reference as a string value instead of following it. This is to prevent the client to bypass the access request otherwise required for soft referenced resources, but not needed for non-soft references. Support for soft references is determined during the version handshake.

[jirenius]

Resolved in #160