Skip to content

PoC integration with FSCHateoasBundle #327

Closed
wants to merge 1 commit into from

5 participants

@lsmith77
FriendsOfSymfony member

just opening this to allow for discussion and brain storming.

this is just a proof of concept to show that its possible to leverage the route collection data to add the hateoas link relations.

a proper implementation would add the metadata during the bootstrap phase of Symfony2. this would prevent the runtime overhead and would ensure that the metadata isnt just linked to specific routes/controllers.

this would probably also allow the removal of the HateoasCollectionInterface

@hjr3
hjr3 commented Nov 23, 2012

I think we should be careful here. HATEOAS is a principle, not an actual design pattern or implementation. When a media type has a certain set of principles it can then be said it is using HATEOAS. The problem I have with the FSCHateoasBundle is that it is too broad. This is akin to wanting to write good object oriented code and creating a SeparationOfConcernsBundle. There are many ways to do separation of concerns just like there are many ways to achieve HATEOAS.

I would like to move in a direction where we write bundles that implement certain media types. There are a few major ones out there right now:
1. Atom+xml
2. Collection+json (this is Atom+xml but the specs are mutually exclusive)
3. Hal+json / Hal+xml

Atom and Collection are great for authoring APIs, such as blogs, newspapers and CMS. The number of H-factors is small and it is easier to understand. Hal is a more general media type that allows for more flexibility. It has more H-factors and can be harder to understand. I think implementing bundles for Hal or Collection/Atom are about the same amount of code though.

At HauteLook, we use Hal+json because there is no defined e-commerce media type out there. The tooling for it has been horrible. We face challenges on both the server side (symfony) and the client side (ember.js) in trying to make Hal+json easy to use. I know @baldurrensch has been working tirelessly with the existing bundles to try and make them more Hal friendly. The PR's are slow to be merged, or even rejected, because people do not understand or disagree with what we are trying to do.

HauteLook is definitely committed to solving the Hal tooling problem with symfony bundles. I just think trying to make a bundle that allows for easier implementation of all media types is just too broad and challenging at this time. Half of the problem any solution is education on how hypermedia works. Focusing on solving specific use cases, such as Hal, allows us to establish a convention. We can publish a README or series of articles that are concrete enough for people to understand and empower them to build hypermedia friendly APIs.

@mvrhov
mvrhov commented Nov 23, 2012

@hradtke: You did see my implementation of hal+json on JSMSerializer bundle.. It's not up to date with the master, but it still works quite fine. Also there is another PR from another author which is supposed to be based on a master.
Either way I don't care which implementation I'm going to use in the future but It has to support at lest what my PR does.
Now regarding the json+hal it's not that hard I find it simple or at least my co-workers did. They had a C++ implementation quite quickly.

Now there is one another format called siren and at a glance it really looks way more complicated than hal+json.

@hjr3
hjr3 commented Nov 23, 2012

@mvrhov Yes, @baldurrensch is the author of the other PR who works with me at HauteLook. I agree that it doesn't matter if JSMSerializer or FOSRestBundle have the actual implementation. We should try, for the communities sake, to keep it together. I know @baldurrensch has had some trouble with getting the PR merged into JSMSerializer.

I don't think hal+json is difficult to understand as a format. However, understanding what affordances Mike Kelly made (and why he made them) is a deeper dive into hypermedia design. Those of us who are students of hypermedia design can grok hal+json, but I would imagine that many people do not really understand it all. My point in mentioning that was only to stress that we establish a convention that is pointing those people who are new to hypermedia APIs in the right direction and try to prevent them from making common mistakes.

Thank you for linking Siren! That looks interesting.

@lsmith77
FriendsOfSymfony member

@hradtke i do agree that its impossible to write a tool that will turn your code into a RESTful application. This is why I have always taken the approach in this Bundle of "use at will tools". Notice that its possible to disable the automatic link relations and add new link relations in this PoC. Also like I was discussing with @ludofleury by linking the configuration to the controller methods, rather than the entity, we can also look into more context aware link relations.

@lsmith77 lsmith77 PoC integration with FSCHateoasBundle
this is just a proof of concept to show that its possible to leverage the route collection data to add the hateoas link relations.

a proper implementation would add the metadata during the bootstrap phase of Symfony2. this would prevent the runtime overhead and would ensure that the metadata isnt just linked to specific routes/controllers.
4c94fe2
@lsmith77
FriendsOfSymfony member

looks like we should instead focus on https://github.com/willdurand/BazingaHateoasBundle now.

@willdurand
FriendsOfSymfony member

The BazingaHateoasBundle leverages the JMSSerializerBundle and the Serializer lib. By simply requiring it, it is able to add links on collections/resources without having to configure anything else (except the metadata for the links, but it is obvious). That means:

  1. add the bundle;
  2. add Hateoas specific annotations to your classes (the ones that are already configured for the Serializer) or use YAML files;
  3. enjoy!
@lsmith77
FriendsOfSymfony member

that was the case with FSCHateoasBundle more or less as well. the goal of this PR is to integrate the information we have about the routes via the route generation.

@adrienbrault

I think that the FOSRestBundle would need to implement a MetadataDriver like https://github.com/willdurand/Hateoas/blob/master/src/Hateoas/Configuration/Metadata/Driver/AnnotationDriver.php . The HateoasBundle could have a DI tag to wire it up.

@lsmith77 lsmith77 closed this Apr 13, 2014
@willdurand
FriendsOfSymfony member

@lsmith77 we could even delete the branch I'd say.

@lsmith77
FriendsOfSymfony member

yeah, i guess its not very useful anymore.

@lsmith77 lsmith77 deleted the poc_fsc_hateoas_integration branch Apr 14, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.