API Platform: Pagination reference

In a nutshell

API Platform provides out-of-the-box support for paged collections. By default, collections will be limited to 30 per page but this per page limit and other behavior can be configured.

When the number of items in a collection endpoint exceeds the per page limit (30 by default), a Hydra collection will be returned that looks something like this:

{
  "@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"
  }
}

Configuration

See current configuration

./bin/console debug:config api_platform collection.pagination

Configure name of the page param (globally)

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

Configure number of items per page (globally)

# api/config/packages/api_platform.yaml
api_platform:
    defaults:
        pagination_items_per_page: 30 # Default value

Configure number of items per page (for resource)

<?php
// api/src/Entity/Book.php
use ApiPlatform\Core\Annotation\ApiResource;
#[ApiResource(attributes: ["pagination_items_per_page" => 30])]
class Book
{
    // ...
}

Disable pagination globally

# api/config/packages/api_platform.yaml
api_platform:
    defaults:
        pagination_enabled: false

Disable pagination for a specific resource

<?php
// api/src/Entity/Book.php
use ApiPlatform\Core\Annotation\ApiResource;
#[ApiResource(attributes: ["pagination_enabled" => false])]
class Book
{
    // ...
}

Allow client to enable or disable the pagination (globally)

# api/config/packages/api_platform.yaml
api_platform:
    defaults:
        pagination_client_enabled: true
    collection:
        pagination:
            enabled_parameter_name: pagination # optional

The pagination can now be enabled or disabled on the client-side by adding a pagination query parameter:

• GET /books?pagination=false: disabled
• GET /books?pagination=true: enabled

Allow client to enable or disable the pagination for a specific resource

<?php
// api/src/Entity/Book.php
use ApiPlatform\Core\Annotation\ApiResource;
#[ApiResource(attributes: ["pagination_client_enabled" => true])]
class Book
{
    // ...
}

Sources

• Pagination – API Platform docs