New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a new "Extending API Platform" documentation entry #866
Comments
To change the behavior of built-in data providers, data persisters etc, service decoration should be used as much as possible. |
Should this entry take the form of page wit the « best practices », or should this information be scattered on the appropriate pages? I’d love to contribute on this one. |
Thank you! |
@dunglas excellent job, would examples in the demo to illustrate the alternate approaches - both the good and bad practices |
@dunglas I started writing this page, but I quickly realized that I'm repeating a lot of what's already written in the other pages, and end up linking to them + linking to the Symfony docs. Maybe this page should actually be broken down and spread into all the appropriate pages. These pages start to be quite complete already, so I'm not sure a lot of info is missing on there. Maybe what could be more useful would be to extend the "Getting started" page to be more of a full tutorial on how to use API Platform (maybe split it into multiple pages then?), and at the end of the tutorial, explaining how to customize the experience further. Taking example from the Symfony components docs, they all have kind of a "tutorial" page, and then, to go further, they have a "reference" page where you can see in details everything you need to use the component to its full potential. What do you think? |
@thib92 could you open a PR with your work so far? It will be easier to review and improve. What I've in mind is to have an entry point describing the big picture of how to extend API Platform, basically based on the text I published in this issue, with links to the appropriate documentation entries both on API Platform's and Symfony's websites, indeed. |
@dunglas done. It's only a draft of the begining of the page for now but maybe this will illustrate what I was saying. |
API Platform now provides good extension points that work for REST and GraphQL APIs the same time. The docs should be updated to explicitly discourage using custom controllers AND Symfony Kernel's events, and instead encourage to use the following extension points:
@ApiResource
must be used instead). Using DTOs and data transformers should be rare. In most cases, using a class marked with@ApiResource
representing the public data model exposed through the API (this class don't have to be mapped with a Doctrine entity, as explained here https://api-platform.com/docs/core/design/). It must not be tight to the internal data model. It's the responsibility of the Data Provider to fetch data from the persistence system and to convert it to a@ApiResource
class. Data Transformers must not be used for this purpose.The text was updated successfully, but these errors were encountered: