PoC integration with FSCHateoasBundle #327
Conversation
|
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:
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. |
|
@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. Now there is one another format called siren and at a glance it really looks way more complicated than hal+json. |
|
@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. |
|
@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. |
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.
|
looks like we should instead focus on https://github.com/willdurand/BazingaHateoasBundle now. |
|
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:
|
|
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. |
|
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 we could even delete the branch I'd say. |
|
yeah, i guess its not very useful anymore. |
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