Document the general design (RAD, CQRS, CQS, event sourcing...) and data persisters #518

dunglas · 2018-06-29T13:51:44Z

Documentation for api-platform/core#1464
Also includes api-platform/core#1747 (comment)

meyerbaptiste · 2018-06-29T13:55:54Z

core/data-persisters.md

+
+* `persist`: to create or update the given data
+* `delete`: to delete the given data
+* `support`: to tell if the given data xcan be handled by this specific data persister


meyerbaptiste · 2018-06-29T13:57:33Z

core/data-persisters.md

+    public function persist($data)
+    {
+      // call your persistence layer to save $data
+      return $data;


IIRC the return type is void.

It has been changed by api-platform/core#1967

alanpoulain · 2018-06-29T14:44:32Z

core/data-persisters.md

+is enabled by default. It is able to persist and delete objects that are also mapped as [Doctrine entities](https://www.doctrine-project.org/projects/doctrine-orm/en/2.6/reference/basic-mapping.html).
+
+However, you may want to store data to other persistence layers (ElasticSearch or MongoDB), to separate the public model
+of the API and the internal model mapped with the database; or to use patterns such as [CQRS](https://martinfowler.com/bliki/CQRS.html)


, instead of ; and remove or?
Missing , after [CQRS](https://martinfowler.com/bliki/CQRS.html)?

No for CQRS, it's the description of CQRS :)

alanpoulain · 2018-06-29T14:48:20Z

core/data-persisters.md

+* `delete`: to delete the given data
+* `support`: to tell if the given data can be handled by this specific data persister
+
+Here is an example implementation:


Missing of?

why? Looks correct to me

https://www.linguee.fr/francais-anglais/traduction/exemple+d%27impl%C3%A9mentation.html

sample implementation then?

Of course I'm not sure at all.

or "implementation example"

https://www.linguee.fr/anglais-francais/traduction/implementation+example.html

alanpoulain · 2018-06-29T14:50:47Z

core/data-persisters.md

+If service autowiring and autoconfiguration are enabled (it's the case by default), you are done!
+
+Otherwise, if you use a custom dependency injection configuration, you need to register the corresponding service and add the
+`api_platform.data_persister` tag to it. As for collection data providers, the `priority` attribute can be used to order


As for collection data providers
As when you have more than one data provider?

it refers to the example in the "collection data providers" docs, maybe should I add a link

Ocramius

I like this kind of "design statement", makes things very clear 👍

sroze · 2018-06-29T16:20:11Z

index.md

@@ -12,16 +12,17 @@
    1.  [Installing API Platform Core](core/getting-started.md#installing-api-platform-core)
    2.  [Before Reading this Documentation](core/getting-started.md#before-reading-this-documentation)
    3.  [Mapping the Entities](core/getting-started.md#mapping-the-entities)
-3.  [Configuration](core/configuration.md)


You could put everything at 1 and don't bother with incrementing everything again, Markdown will do it for you 😉

Yes but it’s less readable when reading the text file directly. Anyway we’re working on a TOC generator. Dropping this file will make contributions lot easier and less error prone.

bendavies

Some general readability comments!

bendavies · 2018-07-01T13:35:22Z

core/data-persisters.md

+
+* `persist`: to create or update the given data
+* `delete`: to delete the given data
+* `support`: to tell if the given data can be handled by this specific data persister


Checks whether the given data is supported by this data persister.

bendavies · 2018-07-01T13:37:05Z

core/data-persisters.md

+}
+```
+
+If service autowiring and autoconfiguration are enabled (it's the case by default), you are done!


it's the case -> they are

bendavies · 2018-07-01T13:38:34Z

core/data-persisters.md

+If service autowiring and autoconfiguration are enabled (it's the case by default), you are done!
+
+Otherwise, if you use a custom dependency injection configuration, you need to register the corresponding service and add the
+`api_platform.data_persister` tag to it.  The `priority` attribute can be used to order persisters.


remove to it

bendavies · 2018-07-01T13:39:41Z

core/data-providers.md

@@ -58,7 +58,8 @@ final class BlogPostCollectionDataProvider implements CollectionDataProviderInte
 }
 ```

-Then declare a Symfony service, for example:
+If you use the default configuration, the corresponding service will be automatically registered thanks to the [autowiring](https://symfony.com/doc/current/service_container/autowiring.html).


the autowiring -> autowiring

bendavies · 2018-07-01T13:43:03Z

core/design.md

+
+Then, it's up to the developer to feed API Platform with an hydrated instance of this API resource object by implementing
+the [`DataProviderInterface`](data-providers.md). Basically, the data provider will query the persistence system (RDBMS,
+document or graph DB, external API...), and must hydrate and return the POPO that has been designed in the first time.


in the first time -> as mentioned above

bendavies · 2018-07-01T13:44:21Z

core/design.md

+document or graph DB, external API...), and must hydrate and return the POPO that has been designed in the first time.
+
+When updating a state (`POST`, `PUT`, `PATCH`, `DELETE` HTTP methods), it's up to the developer to persist properly the
+data provided by API Platform's resource object [hydrated by the serializer](serialization.md) to the persistence system.


remove to the persistence system ?

bendavies · 2018-07-01T13:45:55Z

core/design.md

+data provided by API Platform's resource object [hydrated by the serializer](serialization.md) to the persistence system.
+To do so, there is another interface to implement: [`DataPersisterInterface`](data-persisters.md).
+
+Here is the reverse operation, this class will read the API resource object (the one marked with `@ApiResource`) and:


i'm not sure what Here is the reverse operation is meant to mean here, but doesn't make much sense.

bendavies · 2018-07-01T13:46:36Z

core/design.md

+* or populate an event store;
+* or persist the data in any other useful way.
+
+The logic to execute in data persisters is the responsibility of application developers, and is **out of the API Platform's


The logic to execute in data persisters => The logic of custom data persisters

bendavies · 2018-07-01T13:48:36Z

core/design.md

+* to create projections in standard RDBMS (Postgres, MariaDB...) tables or views
+* to map those projections with read-only Doctrine entity classes **and** to mark those classes with `@ApiResource`
+
+Then you can benefit of all built-in Doctrine filters, sorting, pagination, auto-joins, etc provided by API Platform.


Then you can benefit of all built-in -> You can then benefit from the built-in

bendavies · 2018-07-01T13:50:53Z

core/design.md

@@ -0,0 +1,51 @@
+# General Design Considerations
+
+Because to create a working web API you only need to describe the structure of data to expose, API Platform is both [a "design-first"


Since you only need to describe the structure of the data to expose, API Platform is...

dunglas · 2018-07-04T12:00:39Z

Thank you very much for proof-reading @bendavies!

comments addressed

dunglas requested a review from meyerbaptiste June 29, 2018 13:51

meyerbaptiste mentioned this pull request Jun 29, 2018

Add a data persistence layer api-platform/core#1464

Merged

meyerbaptiste previously requested changes Jun 29, 2018

View reviewed changes

dunglas force-pushed the data-persister branch from 13e7159 to 8d463ee Compare June 29, 2018 14:46

alanpoulain reviewed Jun 29, 2018

View reviewed changes

alanpoulain approved these changes Jun 29, 2018

View reviewed changes

dunglas force-pushed the data-persister branch 2 times, most recently from 9614431 to c1a1fe1 Compare June 29, 2018 15:36

dunglas changed the title ~~Add docs for data persisters~~ Document general design considerations (RAD, CQRS, CQS, event sourcing...) and data persisters Jun 29, 2018

dunglas changed the title ~~Document general design considerations (RAD, CQRS, CQS, event sourcing...) and data persisters~~ Document the general design (RAD, CQRS, CQS, event sourcing...) and data persisters Jun 29, 2018

Ocramius approved these changes Jun 29, 2018

View reviewed changes

dunglas force-pushed the data-persister branch 3 times, most recently from 57c4882 to a272144 Compare June 29, 2018 16:02

sroze reviewed Jun 29, 2018

View reviewed changes

bendavies reviewed Jul 1, 2018

View reviewed changes

dunglas added 2 commits July 4, 2018 14:02

Add docs for data persisters

2df20c2

Add a document presenting general design considerations

b7f20d4

dunglas force-pushed the data-persister branch from d5ff7a8 to b7f20d4 Compare July 4, 2018 12:02

dunglas merged commit 9900196 into api-platform:2.2 Jul 4, 2018

dunglas deleted the data-persister branch July 4, 2018 12:10

		@@ -0,0 +1,51 @@
		# General Design Considerations

		Because to create a working web API you only need to describe the structure of data to expose, API Platform is both [a "design-first"

Uh oh!

Document the general design (RAD, CQRS, CQS, event sourcing...) and data persisters #518

Document the general design (RAD, CQRS, CQS, event sourcing...) and data persisters #518

Uh oh!

Conversation

dunglas commented Jun 29, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Ocramius left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bendavies left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bendavies Jul 1, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dunglas commented Jul 4, 2018

Uh oh!

Uh oh!

dunglas commented Jun 29, 2018 •

edited

Loading

bendavies Jul 1, 2018 •

edited

Loading