HAL compatibility and support not quite there…

[darrin]

First off - thanks for pulling this project together. It looks very promising and if you can use the out of the box Spring HATEOAS support - it seems like you can get a service up and running fast! Unfortunately I have an API Spec that calls for the use of HAL so that option is not available to me.

I'm wondering if there are any plans to do a push to get HAL support in good working order. I've been wresting with spring-hateoas for a day or two as I did so I thought the problems I was running into could be attributed to my newbieness… While that was partially true I've finally come to realize that there are a number of bugs and limitations related to HAL support including but not limited to (in no particular order): #134, #100, #88, #115, #71.

Of course it would be nice if these elements could be fixed because we love Spring but at this point I'm honestly of the mind that if you're using anything but the most basics of HAL spring-hateoas as it stands at the time of this writing - HAL via spring-hateoas is just not ready yet.

I can see there's interest and there's been a good amount of work done by the likes of @fiddlerpianist, @Laures, @chringwer, @dschulten and of course @olivergierke . There are a number of forks, branches (hal-#47) and discussion within issues some of which suggest workarounds. Still for anyone seriously considering the use of spring-hateoas for a production system - the current state of affairs is worrisome at best. What's the scoop with these - is there a plan to make a HAL compatibility/support push anytime soon?

At minimum consider adding a 'HAL Limitations' section to the documents to warn those who follow. It would've saved me a good chunk of effort by informing me that certain features (that are important to us anyway) are just not ready yet… allowing me to choose between moving on to another framework or arguing for alterations in the API spec to more closely conform to Spring's HATEOAS existing implementation.

As for me - it feels like I'll need to find something else to work with until this project is a bit further along (alas we have a tight timeline)… or perhaps roll back to using Spring's REST support and roll-my own rather than wrestling within the bounds of spring-hateoas.

@fiddlerpianist, @Laures, @chringwer, @dschulten - have any of you used this in production? Any thoughts to share before I go off and look elsewhere?

[fiddlerpianist]

Darrin,

My thoughts are that this project provides better support than you're going to get from most other places, and that the spots which are rough around the edges (in this case, HAL) can get ironed out and, hopefully, contributed. I have to agree, however, that I haven't seen a lot of priority given to polishing up the HAL implementation. Last I looked, there are some fundamental things missing that, combined with some really restrictive design choices on the part of Spring HATEOAS, have required me to hack some fundamental constructs (like, for example, the Link class). While that's disappointing (and I hope the designs around such areas become more flexible in the future), most of the heaving lifting has been done.

[fiddlerpianist]

It's great to see HAL now getting first-class support in Spring HATEOAS! It's the default now.

[odrotbohm]

I think we can close this for now due to two reasons:

• Spring HATEOAS, is not a HAL library. It provides a resource abstraction which can be rendered in a HAL compatible way.
• The ticket in itself doesn't add any value over the already existing tickets and lacks scope so that it's hardly anything we can solve "entirely".

Feel free to cast your votes on already existing other tickets or even open up new ones clearly describing something approachable.

[darrin]

I stopped using the project years ago - no doubt the community will speak if they still care. That said - this still seems valid from the original request:

"At minimum consider adding a 'HAL Limitations' section to the documents to warn those who follow. It would've saved me a good chunk of effort by informing me that certain features (that are important to us anyway) are just not ready yet… allowing me to choose between moving on to another framework or arguing for alterations in the API spec to more closely conform to Spring's HATEOAS existing implementation."

It's up to you of course - but looking at the project at a high level - you've had 37 issues opened against this project that mention "HAL". Of them 34 remain open - that's over 25% of your open issues. Collectively that tells a story that your community is interested in this problem and that through this lens not a whole lot has been done to resolve them. Honestly - I don't care whether you plan on trying to address them - but it seems like addressing this in the docs/readme might help to set expectations better with your end users. My thought is - add a roadmap item that could be as vague as 'Better support for HAL' or if you don't plan on addressing these issues then say - 'Limited support for HAL.'.

[odrotbohm]

To be honest, I don't get the frustration. The documentation mention support for HAL as rendering target sparingly. There's absolutely no place in it that say: here's how you work with HAL from start to finish. It's sort of a byproduct because it's needed in downstream projects.

Regarding the number of issues. If you type "HAL" into the search box, you get 34 issues, right. One of them is "Add support for JSON-API", or "ControllerLinkBuilder doesn't work with Groovy". Others have discussion and totally lead somewhere else (like this), some of them (like this one) were asked back at, and never went anywhere. What I am trying to say is: just because a term search matches tickets it doesn't mean those tickets proof that the support for that term is FUBAR.

If we started documenting what we don't support, where would we end? List all media types that have ever existed? "Better support for HAL" is intangible and can — by definition — never be reached anyway, as everyone has a different DOD for that. That has nothing to doe with HAL or Spring HATEOAS, that's just ticket management 101.

[darrin]

I don’t recall seeing that disclaimer about HAL in the docs 2 years ago so perhaps you’ve fixed the misconception I started with so long ago. I remember being pretty frustrated that I’d spent a couple days working with this before I realized it was lacking in an area that I thought was advertised as being present. If this isn’t coming up anymore then I’d say mission accomplished - close with confidence.

As for the document everything you don’t do comment: Consider that you’ve written an extension to Spring to support HATEOAS. One of the most popular standards for HATEOAS is HAL. It is reasonable - even responsible - to document how you support or fall short on supporting the standards that directly relate to HATEOAS - especially if lots of questions / concerns arise about it.

Best, Darrin

On Jan 13, 2016, at 3:34 PM, Oliver Gierke [email protected] wrote:

To be honest, I don't get the frustration. The documentation mention support for HAL as rendering target sparingly. There's absolutely no place in it that say: here's how you work with HAL from start to finish. It's sort of a byproduct because it's needed in downstream projects.

Regarding the number of issues. If you type "HAL" into the search box, you get 34 issues, right. One of them is "Add support for JSON-API", or "ControllerLinkBuilder doesn't work with Groovy". Others have discussion and totally lead somewhere else (like this x-msg://76/#330), some of them (like this one x-msg://76/#276) were asked back at, and never went anywhere. What I am trying to say is: just because a term search matches tickets it doesn't mean those tickets proof that the support for that term is FUBAR.

If we started documenting what we don't support, where would we end? List all media types that have ever existed? "Better support for HAL" is intangible and can — by definition — never be reached anyway, as everyone has a different DOD for that. That has nothing to doe with HAL or Spring HATEOAS, that's just ticket management 101.

—
Reply to this email directly or view it on GitHub #159 (comment).

[odrotbohm]

This is a Git repo. You can track down the history of the reference documentation to it's very beginning. I am pretty sure you won't find a "this is a HAL library" anywhere ever since. That's exactly the reason for my surprise over the frustration. There are quite a few Java libraries out there, that target HAL explicitly. So if that's your cup of tee, please use these (no offense).

The scene of JSON-based hypermedia types is totally fractured these days, and — despite the fact that I like it a lot — HAL is not the ubiquitous hypermedia dialect that I'd like it to be. It has it's benefits, it has its shortcomings. Some of the developers active here have even taken Spring HATEOAS and built more extensive support for media types like Siren etc.

Again, as I said, I am all open to consider concrete feature requests but they might be rejected due to the design constraints we chose. So I really closed the ticket because it's not an approachable (solvable) ticket.

Happy coding!