Using filter in query parameters breaks pagination

[elfin-sbreuers]

API Platform version(s) affected: at least 4.2 and 4.3

Description
When using filters via a nested filter[...] query parameter like:

http://<domain>/api/endpoint?filter[custom]=true

the default pagination parameters stop working as expected:

• page
• itemsPerPage
• pagination

After investigation, it appears that API Platform then expects pagination parameters to also be nested under filter, e.g.:

http://<domain>/api/endpoint?filter[custom]=true&filter[pagination]=false

If no filter[...] parameter is used, pagination works as documented:

http://<domain>/api/endpoint?page=2&itemsPerPage=10

Additionally, the pagination links returned in the response suggest that pagination parameters are still expected at the top level:

"links": {
  "self": "/api/endpoint?filter[custom]=true&reload=true&page=1",
  "first": "/api/endpoint?filter[custom]=true&reload=true&page=1",
  "last": "/api/endpoint?filter[custom]=true&reload=true&page=7",
  "next": "/api/endpoint?filter[custom]=true&reload=true&page=2"
}

This creates an inconsistency between how the API expects parameters and how it advertises them.

Possible Solution
Pagination handling should be independent of how filters are structured. Ideally, pagination parameters (page, itemsPerPage, pagination) should always be accepted at the top level, regardless of whether filters are passed as:

• flat query parameters (?custom=true), or
• nested (?filter[custom]=true)

This would make the behavior more predictable and avoid coupling pagination parsing to filter structure.

Additional Context
The root cause appears to be how $context['filters'] is populated.

When using flat query parameters, pagination values (page, itemsPerPage) are present in $context['filters'] and correctly processed by ApiPlatform\State\Pagination\Pagination.
When using filter[...], only the nested filter values are included in $context['filters'], while pagination parameters remain outside and are therefore ignored by the pagination logic.

This leads to pagination not being applied unless it is also nested under filter[...].

Another source of confusion is the expectation based on the JSON:API specification:

https://jsonapi.org/format/#fetching-pagination
https://jsonapi.org/format/#fetching-filtering
https://jsonapi.org/format/#query-parameters-families

According to the JSON:API spec, query parameter families like filter[...] and page[...] are meant to coexist. Coming from that background, it is natural to structure requests like:

?filter[custom]=true&page[number]=2&page[size]=10

However, API Platform does not follow this convention and instead mixes pagination parameters into the same namespace (filters) internally. This mismatch leads to unexpected behavior when trying to combine structured filtering with pagination.

Clarifying this behavior in the documentation—or aligning parameter handling more closely with JSON:API conventions—would help avoid confusion.

Even more desireable would be to support the JSON:API spec for filtering and pagination when jsonapi is used as content type.

I would try to provide a solution, but I was lost when searching for where the significant portion of the $context variable population is happening.

[soyuka]

comment generated with claude (I'm reviewing manually)

/edit should be straighforward like this, lmk if you want more info or if I misunderstood

Thanks for the detailed report! I think there's a misunderstanding about how JSON:API pagination works in API Platform.

From the JSON:API spec:

JSON API is agnostic about the pagination strategy used by a server, but the page query parameter family can be used regardless of the strategy employed. For example, a page-based strategy might use query parameters such as page[number] and page[size], while a cursor-based strategy might use page[cursor].

page[number]/page[size] are examples, not mandates. API Platform uses page[page]/page[itemsPerPage] — which is equally valid per the spec.

page[page] and filter[...] already work together

When using JSON:API format, this already works out of the box:

GET /api/endpoint?filter[custom]=true&page[page]=2&page[itemsPerPage]=10

The JsonApiProvider handles both filter[...] and page[...] as separate query parameter families and merges them correctly into the internal filters context.

Customizing pagination parameter names with QueryParameter

If you want to use page[number]/page[size] (the JSON:API spec examples) instead of page[page]/page[itemsPerPage], you can achieve this today using QueryParameter with a provider that maps your custom names to what the Pagination service expects:

#[GetCollection(
    formats: ['jsonapi' => ['application/vnd.api+json']],
    paginationItemsPerPage: 10,
    paginationClientItemsPerPage: true,
    parameters: [
        'page[number]' => new QueryParameter(provider: [self::class, 'mapPageNumber']), // this should be in a class but for simplicity we use static functions
        'page[size]' => new QueryParameter(provider: [self::class, 'mapPageSize']),
        'filter[:property]' => new QueryParameter(
            filter: new PartialSearchFilter(),
            properties: ['name'],
        ),
    ],
)]
class MyResource
{
    // ...

    public static function mapPageNumber(Parameter $parameter, array $parameters = [], array $context = []): ?Operation
    {
        $request = $context['request'] ?? null;
        if (!$request || !isset($parameters['page']['number'])) {
            return null;
        }

        $filters = $request->attributes->get('_api_filters', []);
        $filters['page'] = $parameters['page']['number'];
        $request->attributes->set('_api_filters', $filters);

        return null;
    }

    public static function mapPageSize(Parameter $parameter, array $parameters = [], array $context = []): ?Operation
    {
        $request = $context['request'] ?? null;
        if (!$request || !isset($parameters['page']['size'])) {
            return null;
        }

        $filters = $request->attributes->get('_api_filters', []);
        $filters['itemsPerPage'] = $parameters['page']['size'];
        $request->attributes->set('_api_filters', $filters);

        return null;
    }
}

This lets you use ?filter[name]=foo&page[number]=2&page[size]=10 exactly as you'd expect from the JSON:API spec examples.

When you use top-level page=2&itemsPerPage=10 (without the page[...] bracket notation) alongside filter[custom]=true, pagination may not work as expected because the JSON:API JsonApiProvider specifically handles the bracket-based page[...] family. When using JSON:API format, use the bracket notation for pagination: page[page]=2 instead of page=2.

I don't think we need to change the core behavior here — the QueryParameter system gives you the flexibility to customize pagination parameter names per-operation.

[elfin-sbreuers]

Thanks for the detailed answer. I agree, you can circumvent the issue of ignoring the query parameters with this approach. And I also agree with your statement about the opionated design.

It remains the issue that there is an inconsistency that creates confusion for a user and consumer of the API or user of the the framework. I did not find in the documentation a hint, that using filter the top-level pagination features, that were working nicely (disabling pagination from the client, controlling amount of results, etc.), all of a sudden stop working, fall back to configured defaults and need to be wrapped now in a page element.

I guess that should be either documented as a special JSON:API quirk, or they should work in combination. This was one of the questions I posed in the merge request. How do you want to handle this? I would modify the merge request accordingly and remove the opinionated proposal.

[soyuka]

I don't understand, what's the top-level pagination feature you're talking about? When did this break? I'm not even sure how the filter is supposed to work with pagination is this documented anywhere?

[elfin-sbreuers]

Thanks for bearing with me nevertheless.

I mean top-level in the sense of not wrapped in a page[] wrapper.

This is working with my JSONAPI:

http://<domain>/api/endpoint?page=2&itemsPerPage=10

as described here:

https://api-platform.com/docs/core/pagination/

This does not:

http://<domain>/api/endpoint?filter[custom]=true&page=2&itemsPerPage=10

It returns now 25 elements of the first page, since this is configured in the config/packages/api_platform.yaml and the query parameters are ignored.

So adding the filter forces to use filter[page]=2&filter[itemsPerPage]=10 or page[page]&page[itemsPerPage]=10. But without the filter it's working without the wrapping.

I hope that clarifies the confusion and what I mean with inconsistency.