review

Author: dunglas

core/data-persisters.md

@@ -24,7 +24,7 @@ This interface defines only 3 methods:
 
 * `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
+* `support`: checks whether the given data is supported by this data persister
 
 Here is an implementation example:
 
@@ -54,10 +54,10 @@ final class BlogPostDataPersister implements DataPersisterInterface
 }
 ```
 
-If service autowiring and autoconfiguration are enabled (it's the case by default), you are done!
+If service autowiring and autoconfiguration are enabled (they are 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.
+`api_platform.data_persister` tag. The `priority` attribute can be used to order persisters.
 
 ```yaml
 # api/config/services.yaml

core/data-providers.md

@@ -58,7 +58,7 @@ final class BlogPostCollectionDataProvider implements CollectionDataProviderInte
 }
 ```
 
-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).
+If you use the default configuration, the corresponding service will be automatically registered thanks to [autowiring](https://symfony.com/doc/current/service_container/autowiring.html).
 To declare the service explicitly, or to set a custom priority, you can use the following snippet:
 
 ```yaml

core/design.md

@@ -1,8 +1,8 @@
 # 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"
-and "code-first"](https://swagger.io/blog/api-design/design-first-or-code-first-api-development/) API framework.
-However, the "design-first" methodology is strongly recommended: first you design the **public shape** of API endpoints.
+Since you only need to describe the structure of the data to expose, API Platform is both [a "design-first" and "code-first"](https://swagger.io/blog/api-design/design-first-or-code-first-api-development/)
+API framework. However, the "design-first" methodology is strongly recommended: first you design the **public shape** of
+API endpoints.
 
 To do so, you have to write a plain old PHP object representing the input and output of your endpoint. This is the class
 that is [marked with the `@ApiResource` annotation](../distribution/index.md).
@@ -13,21 +13,20 @@ between this class and those docs).
 
 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.
+document or graph DB, external API...), and must hydrate and return the POPO that has been designed as mentioned above.
 
-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.
+When updating a state (`POST`, `PUT`, `PATCH`, `DELETE` HTTP methods), it's up to the developer to properly persist the
+data provided by API Platform's resource object [hydrated by the serializer](serialization.md).
 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:
+This class will read the API resource object (the one marked with `@ApiResource`) and:
 
 * persist it directly in the database;
 * or hydrate a DTO then trigger a command;
 * 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
-scope**.
+The logic of data persisters is the responsibility of application developers, and is **out of the API Platform's scope**.
 
 For [Rapid Application Development](https://en.wikipedia.org/wiki/Rapid_application_development), convenience and prototyping,
 **if and only if the class marked with `@ApiResource` is also a Doctrine entity**, the developer can use the Doctrine
@@ -48,4 +47,4 @@ approach is:
 * 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.
+You can then benefit from the built-in Doctrine filters, sorting, pagination, auto-joins, etc provided by API Platform.