# Pagination

API Platform Core has native support for paged collections. Pagination is enabled by default for all collections. Each collections
contains 30 items per page.
The activation of the pagination and the number of elements per page can be configured from:

* the server-side (globally or per resource)
* the client-side, via a custom GET parameter (disabled by default)

When issuing a `GET` request on a collection containing more than 1 page (here `/books`), a [Hydra collection](http://www.hydra-cg.com/spec/latest/core/#collections)
is returned. It's a valid JSON(-LD) document containing items of the requested page and metadata.

```json
{
  "@context": "/contexts/Book",
  "@id": "/books",
  "@type": "hydra:Collection",
  "hydra:member": [
    {
      "@id": "/books/1",
      "@type": "http://schema.org/Book",
      "name": "My awesome book"
    },
    {
        "_": "Other items in the collection..."
    },
  ],
  "hydra:totalItems": 50,
  "hydra:view": {
    "@id": "/books?page=1",
    "@type": "hydra:PartialCollectionView",
    "hydra:first": "/books?page=1",
    "hydra:last": "/books?page=2",
    "hydra:next": "/books?page=2"
  }
}
```

Hypermedia links to the first, the last, previous and the next page in the collection are displayed as well as the number
of total items in the collection.

The name of the page parameter can be changed with the following configuration:

```yaml
# api/config/packages/api_platform.yaml
api_platform:
    collection:
        pagination:
            page_parameter_name: _page
```

## Disabling the Pagination

Paginating collections is generally accepted as a good practice. It allows browsing large collections without too much
overhead as well as preventing [DOS attacks](https://en.wikipedia.org/wiki/Denial-of-service_attack).
However, for small collections, it can be convenient to fully disable the pagination.

### Globally

The pagination can be disabled for all resources using this configuration:

```yaml
# api/config/packages/api_platform.yaml
api_platform:
    collection:
        pagination:
            enabled: false
```

### For a Specific Resource

It can also be disabled for specific resource:

```php
<?php
// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_enabled"=false})
 */
class Book
{
    // ...
}
```

### Client-side

#### Globally

You can configure API Platform Core to let the client enable or disable the pagination. To activate this feature globally,
use the following configuration:

```yaml
# api/config/packages/api_platform.yaml
api_platform:
    collection:
        pagination:
            client_enabled: true
            enabled_parameter_name: pagination # optional
```

The pagination can now be enabled or disabled by adding a query parameter named `pagination`:

* `GET /books?pagination=false`: disabled
* `GET /books?pagination=true`: enabled

Any value accepted by the [`FILTER_VALIDATE_BOOLEAN`](http://php.net/manual/en/filter.filters.validate.php) filter can be
used as the value.

#### For a specific resource

The client ability to disable the pagination can also be set in the resource configuration:

```php
<?php
// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_client_enabled"=true})
 */
class Book
{
    // ...
}
```

## Changing the Number of Items per Page

In the same manner, the number of items per page is configurable and can be set client-side.

### Globally

The number of items per page can be configured for all resources:

```yaml
# api/config/packages/api_platform.yaml
api_platform:
    collection:
        pagination:
            items_per_page: 30 # Default value
```

### For a Specific Resource

```php
<?php
// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_items_per_page"=30})
 */
class Book
{
    // ...
}
```

### Client-side

#### Globally

```yaml
# api/config/packages/api_platform.yaml
api_platform:
    collection:
        pagination:
            client_items_per_page: true # Disabled by default
            items_per_page_parameter_name: itemsPerPage # Default value
```

The number of items per page can now be changed adding a query parameter named `itemsPerPage`: `GET /books?itemsPerPage=20`

#### For a Specific Resource

Changing the number of items per page can be enabled (or disabled) for a specific resource:

```php
<?php
// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_client_items_per_page"=true})
 */
class Book
{
    // ...
}
```

## Changing Maximum items per page

### Globally

The number of maximum items per page can be configured for all resources:

```yaml
# api/config/packages/api_platform.yaml
api_platform:
    collection:
        pagination:
            maximum_items_per_page: 50
```

### For a Specific Resource

```php
<?php
// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(
 *     attributes={"maximum_items_per_page"=50}
 * )
 */
class Book
{
    // ...
}
```

### For a Specific Resource Collection Operation

```php
<?php
// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(
 *     collectionOperations={
 *         "get"={"maximum_items_per_page"=50}
 *     }
 * )
 */
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
# api/config/packages/api_platform.yaml

api_platform:
    collection:
        pagination:
            partial: true # Disabled by default
```

### For a Specific Resource

```php
<?php

// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_partial"=true})
 */
class Book
{
    // ...
}
```

### Client-side

#### Globally

```yaml
# api/config/packages/api_platform.yaml

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/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_client_partial"=true})
 */
class Book
{
    // ...
}
```

## Avoiding double SQL requests on Doctrine

By default, pagination assumes that there will be collection fetched on a resource and thus will set `useFetchJoinCollection` to `true` on the Doctrine Paginator class. Having this option imply that 2 sql requests will be executed (so this avoid having less results than expected).

In most cases, even without collection on the resource, this parameter has little impact on performance. However when fetching a lot of results per page it can be counter productive.

That's why this behavior can be configured with the `pagination_fetch_join_collection` parameter on a resource:

```php
<?php

// src/Entity/Book.php

use ApiPlatform\Core\Annotation\ApiResource;

/**
 * @ApiResource(attributes={"pagination_fetch_join_collection"=false})
 */
class Book
{
    // ...
}
```

Please note that this parameter will always be forced to false when the resource have composite keys due to a [bug in doctrine](https://github.com/doctrine/doctrine2/issues/2910)