_embedded resources and the self link relation
biddster opened this issue · comments
I'm returning a collections of items from a resource. I assemble a hal response using .withSubresource("echo", subRes) where I supply a relation of "echo". In each of my sub-resources, the self link relation is prefixed with the relation name I passed to .withSubresource(). ie "echo self".
I wasn't expecting this to be the case. Once I've traversed using _embedded.echo[0]._links, I was expecting to deal in standard link relation nomenclature, ie be able to use self, not have to know that I have to prefix the parent link relation name.
None of the examples that I've seen indicate this is expected...
http://blog.stateless.co/post/13296666138/json-linking-with-hal
Happy to accept I've missed the point so feel free to flame and clarify :-)
Thanks for the great work.
Under the original specification, it was unclear that resource and link rel's in HAL were single reltypes, and implied they carried the same structure of a rel attribute in the web linking spec, which is a space separated list of reltypes - so technically the HalBuilder library was correct - in that the link with a rel of "self echo" was shortland for having two links, each with "self" and "echo" respectively.
Originally, HalBuilder was keeping the rel for WHY it was embedded on the embedded resource itself, so the self link was being collapsed into one link.
However, the current specification being put forward to IETF clarifies this by stating its a reltype.
It is an object whose property names are link relation types (as defined by [RFC5988])
With the plural of names/types being referenced I take this to mean "each property name is a link relation type".
The current 2.0.1-SNAPSHOT builds ( from source ) now correctly separate an embedded resources embedding reltype ( why its embedded ) from the links on the embedded resource itself.
Do you still see this behavior on the current 2.0.1 builds ( note that if you're coming from the 1.x version, EVERYTHING is changed - classes are now called Representation rather Resource, and the package has changed and been split into separate repositories ( and no longer bleeds out Google Guava Optionals ).
I need to write up some migration docs for all this actually :)
Thank you for all your efforts with this project - it has been very helpful. Would you recommend migrating to the 2.0.1 builds sooner rather than later? I'm currently using 1.0.5 for a project and I'd like to be solid ground for creating my representations. Is there a plan to push them to Maven Central?
Well the 1.0x branches are now unmaintained, and I hope to start releasing 2.x versions soon as I'll likely be using that in an upcoming project stream at work. I like the direction I'm now heading with the separate artifacts and extension modules, but would also be good to get some feedback from anyone using it first ( mind you - afaik theres only about 3 people so far, that I know of ).
The plan is to definitely push to central and the sooner the better.
Thanks for getting back to me. I'm using your library in my MultiBit
Merchant project (see
https://github.com/gary-rowe/MultiBitMerchant/wiki/Introduction for an
overview) and have found it to be a much better solution that my own dodgy
attempt after I first discovered HAL.
For some trivial code examples see
https://github.com/gary-rowe/MultiBitMerchant/blob/develop/mbm/src/main/java/org/multibit/mbm/api/response/hal.
To give you some context, your library forms the bridge between the domain
objects/DTOs and the client response which is served through the Dropwizard
framework.
I would certainly appreciate any advice you could offer regarding the use
of the library (documentation is a little thin), or perhaps you might be
interested in using MBM as a potential showcase for a real application. I'm
happy to write this advice up as suitable Javadocs for the ResourceFactory
etc and issue it as a pull request against v1.0.x or v2.0.x.
I am able to work on my MBM project full time for the next 4 weeks so if
this offer is helpful to you, please let me know.
On 30 September 2012 06:54, Mark Derricutt notifications@github.com wrote:
Well the 1.0x branches are now unmaintained, and I hope to start
releasing 2.x versions soon as I'll likely be using that in an upcoming
project stream at work. I like the direction I'm now heading with the
separate artifacts and extension modules, but would also be good to get
some feedback from anyone using it first ( mind you - afaik theres only
about 3 people so far, that I know of ).The plan is to definitely push to central and the sooner the better.
—
Reply to this email directly or view it on GitHubhttps://github.com/HalBuilder/halbuilder-java/issues/3#issuecomment-9011154.
@talios Brilliant explanation. I'm using 1.x simply because it's available in Maven central. I'll be sure to try the 2.x builds and feed back to you.
@gary-rowe I like the look of MultiBitMerchant - will definitely have to call it out in an upcoming blog post about 2.0.1, I notice you've got a MinifiedJsonRenderer - is the lack of pretty-printing the only difference between this and the original ( I only had a quick glance ), sounds like something that might be a good option to include on the default ones and configured on the RepresentationFactory instance.
@biddster Cheers! As something that started as both an hack to see how the HAL format would play out, and an experiment in API design I think both have worked out reasonably well - with a few rough edges remaining.
This conversation should probably really take place on the mailing list, but what the hell - just posted to my tumblr about 2.0.1 - http://www.theoryinpractice.net/post/32729432438/halbuilder-2-0-1-progress
@talios Thanks for looking over MBM. As you point out, the MinifiedJsonRenderer is there because I didn't want the pretty pritining JSON and, yes, having it as an option for the RepresentationFactory would be a good design choice.
I've made extensive updates to MBM recently, particularly in the HAL representation area, if you feel inclined, you may want to conduct a second review. You'll notice that I've gone for a design based on composition which gives a good way to assembly arbitrary representations.