HAL-FORMS: Spring HATEOAS Implementation

185 views
Skip to first unread message

Samih ELJ

unread,
Jan 22, 2020, 9:01:30 AM1/22/20
to HAL Discuss
Hello,

I was looking at Mike Amundsen's HAL-FORMS extension and found an implementation made by the Spring HATEOAS Team.
If you look at the example, you'll find that they include the _template as a root attribute of the JSON-HAL Document itself, so we can't handle actions on more than one resource..

Am I wrong if I say that this implementation is not conform to the specification? 

{
  "firstName" : "Frodo",
  "lastName" : "Baggins",
  "role" : "ring bearer",
  "_links" : {
    "self" : {
    }
  },
  "_templates" : {
    "default" : {
      "method" : "put",
      "contentType" : "",
      "properties" : [ {
        "name" : "firstName",
        "required" : true
      }, {
        "name" : "lastName",
        "required" : true
      }, {
        "name" : "role",
        "required" : true
      } ]
    },
    "partiallyUpdateEmployee" : {
      "method" : "patch",
      "contentType" : "",
      "properties" : [ {
        "name" : "firstName",
        "required" : false
      }, {
        "name" : "lastName",
        "required" : false
      }, {
        "name" : "role",
        "required" : false
      } ]
    }
  }
}

--
Samih

mca

unread,
Jan 22, 2020, 4:37:01 PM1/22/20
to hal-discuss@googlegroups com
well, i think there are two things to address here. let's see if i come close to responding to your comment.

1) the _templates element is "inlined" into a HAL doc. that was not the original intent. MIke Kelly and I talked about this and we both thought the appropriate approach was to keep HAL-FORMS documents separate (like CSS documents or Javascript files) and then refer to them as described in the HAL-FORMS docs here: https://rwcbook.github.io/hal-forms/#_suggested_process_flow_for_hal_forms_documents

But i've seen others do the same thing (inlining _templates). *technicaly* HAL spec doesn't *prevent* this, i guess.

2) the ability to ship more than a single form in a response was accounted for in the HAL-FORMS spec, but not clearly defined. that's my mistake. I think I talked w/ the Spring team about this but can't recall the thread ATM. the current spec says 

key : The unique identifier for this template object. This is a REQUIRED element. For this release, the only valid value for key is "default"

that's overly controlling language. it should say "For this release, the only defined value for key is "default". Additional language is needed tho. something like "The _templates graph MUST contain at least one template but it MAY contain more. If there is only one template in the _templates collection, the key value of that template SHOULD be "default", however it MAY be set to any other valid string value." that's just an off-the-cuff attempt.

essentially, the _templates collection may have multiple templates and they could be referenced using the "_hkey" value in a query against the HAL-FORMS document. when the template is inlined (like the example you shared) we need to make it clear how clients should be able to find the "appropriate" template. (might be no added spec writing here, but maybe there is some guidance needed.

does this cover what you expected? is there something else going on we should address?

Mike Amundsen



--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/2e0f1819-e3ca-451c-891d-81065acb5233%40googlegroups.com.

Samih ELJ

unread,
Jan 23, 2020, 11:00:38 AM1/23/20
to hal-d...@googlegroups.com
Thank you for your answer,
for the 1) that's what I understood, and I like the fact it allows consumer to check or not the action description (event if IMHO, consumers SHOULD NOT hardcode action calls if a HAL FORMS document is associated to the representation)

 I think that the inlining prevent from describing actions on other URIs thant the "self" link of the HAL representation.
Let's consider an example  :
{ 
  "orderId": "1234", 
  "_links" : {
      "self" : {
           "href": "http://example.com/orders/1234"
       },
       "deliveryAddress": {
            "href": "http://example.com/orders/1234/delivery-address"
        }
     }
}

If we inline the template, I would'nt be able to specify a "defineDeliveryAddress" on the "deliveryAdress" URI without performing a GET on it to get the HAL-FORMS inlined (I may also not want to expose a GET on the delivery address URI...)
have you considered defining a reference to the HAL link object inside a template object ?
For example (if we consider the example above)
{
   "_templates": {
         " defineDeliveryAddress": {
              "title" : " Define a delivery address",
...
}
}
}

Regards
--
Samih


To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/CAPW_8m6UQ6wFv9M0RHog%2BdJHQRh2WSNsDqvYT2o%2Bra3rRoNNtA%40mail.gmail.com.


--
Samih
06 67 71 99 82

mca

unread,
Jan 23, 2020, 11:34:34 PM1/23/20
to hal-discuss@googlegroups com
not sure if this is what you mean but...

1) HAL-FORMS spec is designed to take advantage of HAL's feature that rels can be valid URLs.
2) those rel-URLs can point anywhere (for example "http://example.org/deliveryAdddress")
3) HAL-FORMS allows multiple templates in the same "_template" block (example "_templates.deliveryAddress...")
4) as i mentioned the HAL-FORMS spec is unclear on how to easily translate the rel-URL into an inline reference. but i think this can be fixed pretty easily

now, i can't speak to how Spring HAL/HAL-FORMS implementation works, so there may be other issues in folves.

finally, i don't think the current situation is a big problem (but it might be viewed as annoying). IOW, making a call to retrieve the form description is relatively easy. that was my original design -- not a collect of inlined forms, but a way to use the "_links" collect to find and call the form you need at the moment.

i hope this addresses your point. feel free to correct my misunderstanding and/or continue the convo.

cheers.
 





Mike Amundsen


To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/CA%2B_rYTP%3DiYMGwYRMbj_AD%3DnXtgSrXExa5M0CFn90mLXQ%3D6GyOA%40mail.gmail.com.

Samih ELJ

unread,
Jan 24, 2020, 7:09:50 AM1/24/20
to hal-d...@googlegroups.com
Thank you Mike, it's very clear.
 I'll try to discuss with Spring Hateoas team about this. 

Regards
--
Samih

To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/CAPW_8m5SMaZ9YJOnfSEJaFSBW2GJU%2BxPt%3DskK2p881mma2bkYg%40mail.gmail.com.

mca

unread,
Jan 24, 2020, 8:52:49 AM1/24/20
to hal-discuss@googlegroups com
if the spec needs some tweaks along the way, feel free to let me know and we'll work on it.


Mike Amundsen


To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/CA%2B_rYTMXkbpN82rEE0nU%2BVfq8jouXRgPJO9oP41viX14suemPQ%40mail.gmail.com.

Oliver Drotbohm

unread,
Jan 24, 2020, 10:40:13 AM1/24/20
to HAL Discuss
Just to clarify: Spring HATEOAS does not have an opinion on whether you use _template in a separate document or inline it. That's all under user control as she decides what affordances are registered when producing the model for the initial resource. So it's perfectly fine to produce a plain HAL response on first request and expose additional resources that'd return the corresponding HAL FORMS form separately as suggested in the spec. If you register the affordances on the model created for the initial request, we will render those if content negotiation ends up deciding for HAL FORMS. You can tweak that by either forcing a controller method into using plain HAL by explicitly setting produces="…" in the mapping annotation of your controller method or simply not add the affordance which also makes sense if you explicitly want to expose HAL only in the first place.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-d...@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-d...@googlegroups.com.


--
Samih
06 67 71 99 82

--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-d...@googlegroups.com.

--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-d...@googlegroups.com.


--
Samih
06 67 71 99 82

--
You received this message because you are subscribed to the Google Groups "HAL Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to hal-d...@googlegroups.com.

mca

unread,
Jan 24, 2020, 10:42:21 AM1/24/20
to hal-discuss@googlegroups com
thanks for that clarification, Oliver.

and for supporting HAL-FORMS!


Mike Amundsen


To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/874d80ba-91b1-4cbe-b059-1d0ac2432d86%40googlegroups.com.

Samih ELJ

unread,
Jan 24, 2020, 11:07:04 AM1/24/20
to hal-d...@googlegroups.com
Thank you Oliver, 
I created an issue here https://github.com/spring-projects/spring-hateoas/issues/1188 , may be we should continue the discussion there :)

To unsubscribe from this group and stop receiving emails from it, send an email to hal-discuss...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/hal-discuss/874d80ba-91b1-4cbe-b059-1d0ac2432d86%40googlegroups.com.
Reply all
Reply to author
Forward
0 new messages