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.
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
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:
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:Considerations
"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."soft": true
as property (as oppose to"hard": false
) does more obviously default tofalse
when the property is missing.