spring-projects / spring-projects/spring-hateoas

HAL-FORMS: problems with the inlining mecanism

Open
#1,188 12 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
1.1k
Forks
476
PR merge metrics
No merged PRs in 30d

Description

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"
                 }
            }
        }
    }
}

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the HAL-FORMS specification and the linked Spring HATEOAS example, then inspect the repository for the HAL-FORMS inlining implementation. Define the expected representation for templates attached to non-self links and confirm the behavior with focused tests; done requires an agreed implementation that supports the command-style links described here.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.