HAL-FORMS: problems with the inlining mecanism

The HAL-FORMS specification do not use the inlining mecanism, and rather recommends separating HAL and HAL FORMS documents. If I understood the implementation by Spring HATEOAS in this example, I think it reduces the features that can be offered by an API.

Let’s consider an example with a resource “issue” (/issues/{id}). When performing a GET, I want to see its details + some hypermedia controls to tell me how to “update the details”, how to “assign” it, how to “cancel” it and how to “mark it resolved”. And I want all this actions to be performed in a “command style” resources and not as direct updates of the “issue” resource.

The actual implemented iniling do not allow this design… because there is no way to reference an URI from the _template, it’s all implicitly linked to the self relation.

If the template object was inlined into a link object, then it would be possible to do that.

{
    "_links": {
        "self": {
            "href": "/issues/1",
            "_templates": {
                 "default": {
                      "title":  "update",
                      "method" : "PUT"
                      
                 }
            }
        },
        "assignCommand" : {
            "href" :  "/issues/1/assign-commands",
            "_templates": {
                "default" : {
                      "title":  "assign",
                      "method" : "POST",
                      "other" :" Attributes"
                 }
            }
        },
        "resolveCommand" : {
            "href" :  "/issues/1/resolve-commands",
            "_templates": {
                "default" : {
                      "title":  "resolve",
                      "method" : "POST",
                      "other" :" Attributes"
                 }
            }
        },
        "cancelCommand" : {
            "href" :  "/issues/1/cancel-commands",
            "_templates": {
                "default" : {
                      "title":  "cancel",
                      "method" : "POST",
                      "other" :" Attributes"
                 }
            }
        }
    }
}

[gregturn]

Inside HalFormsTemplateBuilder, if I replace…

List<Affordance> affordances = resource.getLink(IanaLinkRelations.SELF) //
        .map(Link::getAffordances) //
        .orElse(Collections.emptyList());

…with…

List<Affordance> affordances = resource.getLinks().stream()
    .flatMap(link -> link.getAffordances().stream())
    .collect(Collectors.toList());

…then this…

RepresentationModel<?> model = new RepresentationModel<>();

Link selfLink = Affordances.of(Link.of("/issues/1")) //
        .afford(HttpMethod.PUT) //
        .withName("update") //
        .toLink();

Link assignCommand = Affordances.of(Link.of("/issue/1/assign-commands", LinkRelation.of("assignCommand")))
    .afford(HttpMethod.POST) //
    .withName("assignCommand") //
    .toLink();

Link resolveCommand = Affordances.of(Link.of("/issue/1/resolve-commands", LinkRelation.of("resolveCommand")))
    .afford(HttpMethod.POST) //
    .withName("resolveCommand") //
    .toLink();

Link cancelCommand = Affordances.of(Link.of("/issue/1/cancel-commands", LinkRelation.of("cancelCommand")))
    .afford(HttpMethod.POST) //
    .withName("cancelCommand") //
    .toLink();

model.add(selfLink, assignCommand, resolveCommand, cancelCommand);

System.out.println(this.mapper.writeValueAsString(model));

…will yield this HAL-FORMS document…

{
  "_links" : {
    "self" : {
      "href" : "/issues/1"
    },
    "assignCommand" : {
      "href" : "/issue/1/assign-commands"
    },
    "resolveCommand" : {
      "href" : "/issue/1/resolve-commands"
    },
    "cancelCommand" : {
      "href" : "/issue/1/cancel-commands"
    }
  },
  "_templates" : {
    "default" : {
      "method" : "put",
      "properties" : [ ]
    },
    "cancelCommand" : {
      "method" : "post",
      "properties" : [ ]
    },
    "resolveCommand" : {
      "method" : "post",
      "properties" : [ ]
    },
    "assignCommand" : {
      "method" : "post",
      "properties" : [ ]
    }
  }
}

[samihus]

According to the HAL FORMS spec, _templates is a top-level property.

True, but in a HAL FORMS Document. If we consider that HAL FORMS document is identified by the relation in the Link object of the HAL document, then inlining it should be under the link object it refers to. Not at a global level…