doc partial pagination (api-platform#266)

* doc partial pagination

* Fix Markdown syntax highlighting

Author: soyuka

core/configuration.md

@@ -79,7 +79,7 @@ api_platform:
 
     swagger:
         # The swagger api keys.
-        api_keys: []      
+        api_keys: []
 
     collection:
         # The default order of results.
@@ -113,6 +113,16 @@ api_platform:
             # The name of the query parameter to set the number of items per page.
             items_per_page_parameter_name: 'itemsPerPage'
 
+            # To allow partial pagination for all resource collections.
+            # This improves performances by skipping the `COUNT` query.
+            partial: true
+
+            # To allow the client to enable or disable the partial pagination.
+            client_partial: true
+
+            # The name of the query parameter to enable or disable the partial pagination.
+            partial_parameter_name: 'partial' # Default value
+
     mapping:
         # The list of paths with files or directories where the bundle will look for additional resource files.
         paths: []

core/pagination.md

@@ -205,6 +205,76 @@ class Book
 }
 ```
 
+## Partial Pagination
+
+When using the default pagination, a `COUNT` query will be issued against the current requested collection. This may have a
+performance impact on really big collections. The downside is that the information about the last page is lost (ie: `hydra:last`).
+
+### Globally
+
+The partial pagination retrieval can be configured for all resources:
+
+```yaml
+# app/config/config.yml
+
+api_platform:
+    collection:
+        pagination:
+            partial: true # Disabled by default
+```
+
+### For a Specific Resource
+
+```php
+<?php
+
+// src/AppBundle/Entity/Book.php
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(attributes={"pagination_partial"=true})
+ */
+class Book
+{
+    // ...
+}
+```
+
+### Client-side
+
+#### Globally
+
+```yaml
+# app/config/config.yml
+
+api_platform:
+    collection:
+        pagination:
+            client_partial: true # Disabled by default
+            partial_parameter_name: 'partial' # Default value
+```
+
+The partial pagination retrieval can now be changed by toggling a query parameter named `partial`: `GET /books?partial=true`
+
+#### For a Specific Resource
+
+```php
+<?php
+
+// src/AppBundle/Entity/Book.php
+
+use ApiPlatform\Core\Annotation\ApiResource;
+
+/**
+ * @ApiResource(attributes={"pagination_client_partial"=true})
+ */
+class Book
+{
+    // ...
+}
+```
+
 Previous chapter: [Validation](validation.md)
 
 Next chapter: [The Event System](events.md)

core/performance.md

@@ -219,6 +219,23 @@ api_platform:
 
 The whole configuration seen before will no longer work and Doctrine will recover its default behavior.
 
+### Partial Pagination
+
+When using the default pagination, the Doctrine paginator will execute a `COUNT` query on the collection. The result of the
+`COUNT` query is used to compute the latest page available. With big collections this can lead to quite long response times.
+If you don't mind not having the latest page available, you can enable partial pagination and avoid the `COUNT` query:
+
+```yaml
+# app/config/config.yaml
+
+api_platform:
+    collection:
+        pagination:
+            partial: true # Disabled by default
+```
+
+More details are available on the [pagination documentation](pagination.md#partial-pagination).
+
 Previous chapter: [Security](security.md)
 
 Next chapter: [Operation Path Naming](operation-path-naming.md)

index.md

@@ -54,6 +54,7 @@
 9.  [Pagination](core/pagination.md)
     1.  [Disabling the Pagination](core/pagination.md#disabling-the-pagination)
     2.  [Changing the Number of Items per Page](core/pagination.md#changing-the-number-of-items-per-page)
+    3.  [Partial Pagination](core/pagination.md#partial-pagination)
 10.  [The Event System](core/events.md)
 11. [Content Negotiation](core/content-negotiation.md)
     1.  [Enabling Several Formats](core/content-negotiation.md#enabling-several-formats)
@@ -80,6 +81,7 @@
             2.  [Force Eager](core/performance.md#force-eager)
             3.  [Override at Resource and Operation Level](core/performance.md#override-at-resource-and-operation-level)
             4.  [Disable Eager Loading](core/performance.md#disable-eager-loading)
+        3.  [Partial Pagination](core/performance.md#partial-pagination)
 18. [Operation Path Naming](core/operation-path-naming.md)
     1.  [Configuration](core/operation-path-naming.md#configuration)
     2.  [Create a Custom Operation Path Naming](core/operation-path-naming.md#create-a-custom-operation-path-resolver)