Skip to content
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

Closed
11 tasks
dunglas opened this issue Sep 5, 2019 · 7 comments
Closed
11 tasks

Add a new "Extending API Platform" documentation entry #866

dunglas opened this issue Sep 5, 2019 · 7 comments

Comments

@dunglas
Copy link
Member

dunglas commented Sep 5, 2019

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:

  • Data Provider: Fetch data, custom computation, custom hydration
    • Alternative when using the built-in Doctrine data provider: use extensions and create custom Doctrine hydrators
  • Symfony Denormalizer: to customize the object computed from the JSON payload
  • Symfony Voter: to hook custom authorization logic
  • Symfony Validation constraint: to hook custom validation logic
  • Data Persister: to hook custom business logic or computation to trigger before, during or after persistence (ex: mail, call to an external API…)
  • Symfony Normalizer: to customize the output (add field in the JSON, encode codes, dates…)
  • Symfony Messenger integration: to create RPC, async, service-oriented endpoints, should be used in place of custom controllers (because the messenger integration is compatible with both REST and GraphQL, while custom controllers only work with REST)
  • DTOs and data transformers: to create specialized representations of a (usually large) object or graph of objects also available through their own endpoints (for internal objects, a simple data provider and a public @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.
  • Symfony Kernel Event Listener: Customize the HTTP request or response (REST only, last resort solution)
  • TODO: use the error handler (new component) to hook custom error handling logic (see also Fix compatibility with symfony/error-renderer core#2972)
@dunglas
Copy link
Member Author

dunglas commented Sep 5, 2019

To change the behavior of built-in data providers, data persisters etc, service decoration should be used as much as possible.

@thib92
Copy link

thib92 commented Sep 5, 2019

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.

@dunglas
Copy link
Member Author

dunglas commented Sep 5, 2019

Thank you!
Both would be great: a main page, and references to it in the the existing pages!

@ssmusoke
Copy link
Contributor

ssmusoke commented Sep 7, 2019

@dunglas excellent job, would examples in the demo to illustrate the alternate approaches - both the good and bad practices

@thib92
Copy link

thib92 commented Sep 11, 2019

@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?

@dunglas
Copy link
Member Author

dunglas commented Sep 18, 2019

@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.

@thib92
Copy link

thib92 commented Sep 24, 2019

@dunglas done. It's only a draft of the begining of the page for now but maybe this will illustrate what I was saying.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants