Add CURIE support for embedded resources

[irieill]

In my reading of the HAL-draft it is perfectly valid to use CURIE syntax for the link relation type of embedded properties. To serialize the following "hypertext cache pattern" JSON:

{
  "_links": {
    "curies": [
      {
        "href": "http://example.org/relations/foo/{rel}",
        "templated": true,
        "name": "foo"
      }
    ],
    "foo:bars": [
      {
        "href": "http://example.org/bars/248875bd-c7e1-357f-8473-450cc49a8308"
      }
    ],
    "self": {
      "href": "http://example.org/bars"
    }
  },
  "_embedded": {
    "foo:bars": [
      {
        "_links": {
          "self": {
            "href": "http://example.org/bars/248875bd-c7e1-357f-8473-450cc49a8308"
          }
        },
        "uuid": "248875bd-c7e1-357f-8473-450cc49a8308"
      }
    ]
  },
  "count": 1
}

Currently someone needs to provide a fixed CURIE value for the embedded resource:

@Resource
@Curie(prefix = "foo", href = "http://example.org/relations/foo/{rel}"
public class Bars {

  private HALLink self;
  private List<Bar> barResources;
  private List<HALLink> barLinks;
  private Integer count;

  public (HALLink self, List<Bar> bars) {
    this.self = Objects.requireNonNull(self);
    this.barResources = Objects.requireNonNull(bars);
    this.barLinks = bars.stream().map(bar -> bar.getSelf()).collect(Collectors.toList());
    this.count = Integer.valueOf(bars.size());
  }

  @Link
  public HALLink getSelf() {
    return this.self;
  }

  @EmbeddedResource(value = "foo:bars")
  public List<Bar> getBarResources() {
    return this.barResources;
  }


  @Link(curie = "foo", value = "bars")
  public List<HALLink> getBarLinks() {
    return this.barLinks;
  }

  public Integer getCount() {
    return this.count;
  }

}

It would be nice if someone could use @EmbeddedResource(curie = "foo", value = "bars") (as with @Link).

[arucard21]

I think it might be fairly easy to do this by adding the curie parameter to the annotation (as you showed) and modifying this method to also allow a curie parameter (similar to the methods below it for links). I'm not sure if that would break anything else though (but that's why you have tests).

If you want, you could try implementing it and submit a pull request for it.

[irieill]

If you want, you could try implementing it and submit a merge request for it.

That would be very nice. Thank you.

[langecode]

Yeah, I guess it would make sense also following the hypertext cache pattern. However, don't we have a semantic issue. Been a while since I read the HAL spec draft but as far as I recall the curies are only defined in the _links object - it would seem a little bit inconsistent to use a curie defined in _links for templating a relation in _embedded - unless, of course, the assumption is that you cannot have anything in the _embedded object unless it is also present in _links - that would possibly make sense.

I agree the implementation must adhere to the @Link implementation with a curie property - mostly to be able to validate it against the list of defined curies.

[arucard21]

The HAL spec does only specify to use a curies link in the _links object. But that curies link is intended to define the CURIEs used in the entire document, not just within the _links object.

Custom link relation types (Extension Relation Types in [RFC5988]) SHOULD be URIs that [...]

The CURIE Syntax [W3C.NOTE-curie-20101216] MAY be used for brevity for these URIs. CURIEs are established within a HAL document via a set of Link Objects with the relation type "curies" on the root Resource Object.

Those CURIEs defined in the curies link can then be used to shorten the custom Link Relation URIs, anywhere in the document. And both _links and _embedded are defined to use Link Relations as name.
_links

It is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects.

_embedded

It is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Resource Object or an array of Resource Objects.

So I think there shouldn't be a semantic problem here. This should entirely conform to the spec.

[langecode]

Great - then by all means let's have support on the embedded objects as well :-)

[irieill]

However, don't we have a semantic issue. Been a while since I read the HAL spec draft but as far as I recall the curies are only defined in the _links object - it would seem a little bit inconsistent to use a curie defined in _links for templating a relation in _embedded - unless, of course, the assumption is that you cannot have anything in the _embedded object unless it is also present in _links - that would possibly make sense.

I am also not sure about the semantic issue. Therefore i began with in my reading. I will quote and comment some points from the spec draft.

4.1.1. _links

The reserved "_links" property is OPTIONAL.

It is an object whose property names are link relation types (as
defined by [RFC5988]) and values are either a Link Object or an array
of Link Objects. The subject resource of these links is the Resource
Object of which the containing "_links" object is a property.

For me this is a validity scope declaration about the full resource, also for CURIEs (as they are special links).

4.1.2. _embedded

The reserved "_embedded" property is OPTIONAL

It is an object whose property names are link relation types (as
defined by [RFC5988]) and values are either a Resource Object or an
array of Resource Objects.

Self explanatory.

8.2. Link relations

Custom link relation types (Extension Relation Types in [RFC5988])
SHOULD be URIs that when dereferenced in a web browser provide
relevant documentation, in the form of an HTML page, about the
meaning and/or behaviour of the target Resource. This will improve
the discoverability of the API.

The CURIE Syntax [W3C.NOTE-curie-20101216] MAY be used for brevity
for these URIs. CURIEs are established within a HAL document via a
set of Link Objects with the relation type "curies" on the root
Resource Object. These links contain a URI Template with the token
'rel', and are named via the "name" property.

Not restricting CURIE syntax to _links elemtens only. Just says where CURIEs are established, not what scope they are valid in. But this also implies, that CURIEs esteblishment is not allowed on embedded resources _links as they are not the root resource obviously.

8.3. Hypertext Cache Pattern

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.

Well some can argue that same means semantical but not syntactical. Sadly there is some lack of examples for embedded resources with CURIEs. But i think it is perfectly valid.

While writing @arucard21 replyed with similar quotes and comments. So i think we read this correctly.

[langecode]

Yes, I agree with you both. Makes sense to support curies for the embedded objects as well - certainly. I am not actively using Java currently and there are different issues laying around on these projects so I will reserve some time soon to get some new releases out - this should make it in such a maintenance release.

…