Feature request - custom pagination

[theofidry]

As of now it is possible to customize the number of items per page at a global level on the API side with the option items_per_page.

But the number of items per page is a parameter you may wish to change for some entities on the API side and sometimes let the client adjust it to his need.

To cover most of the use case without having to override a DataProvider a defining a custom Paginator, tit should be possible to configure the following with some parameters in the config:

1. Configure the items_per_page on a global basis on the API side (already possible)
2. Configure the items_per_page on a resource basis on the API side
3. Enable the possibility for the client to change the default page size for all resources
4. Enable the possibility for the client to change the default page size on a resource basis

Suggestion of configuration

Feature 1

Keep it as it is.

Feature 2

services:
    resource.dummy:
        parent:    "api.resource"
        arguments: [ "AppBundle\Entity\Dummy" ]
        calls:
            -      method:    "setPagination"
                   arguments: 50

And in this case, regardless of the value of items_per_page in the config.yml, this pagination for Dummy will be at 50.

Feature 3

Since it's for all the resources it seem logical to define it in the config.yml:

dunglas_api:
    title:              "Your API name"
    description:        "The full description of your API"
    default:
        items_per_page:
            default_value:     30
            client_pagination: true # Default to false
        order:          ~

Maybe adding which values we allow for the pagination via a request would be nice too. If you deem it too specific then letting the user extending the paginator to achieve that is fine.

Feature 4

services:
    resource.dummy:
        parent:    "api.resource"
        arguments: [ "AppBundle\Entity\Dummy" ]
        calls:
            -      method:    "enableClientPagination"
                   arguments: [10, 50, 100, 200] # valid values, if no value provided all value is accepted.

Syntax

Syntax proposal for the custom pagination on the client side:

url?itemsPerPage=value

[dunglas]

This feature has been partially contributed by @amenophis in #44

It can be features 2 + 3 + 4 :)

[theofidry]

Ok, just waiting for you to finish the doc before closing this ticket then.

[theofidry]

@dunglas since the PR has been merged and from what I see all the features has been added by now but I do not see it in the doc though.

[theofidry]

I was thinking of updating the doc. Should I put it in a dedicated chapter or to append it in an existing one?

[theofidry]

Update on the issue:

1 +3 is already handled and documented here.

1 + 2 is possible be requires to declare a custom DataProvider like the following:

resource.dummy.data_provider:
    class:    Dunglas\ApiBundle\Doctrine\Orm\DataProvider
    arguments:
        - @doctrine
        - %api.collection.order%
        - %api.collection.pagination.page_parameter_name%
        - %api.collection.pagination.items_per_page.number%
        - %api.collection.pagination.items_per_page.enable_client_request%
        - %api.collection.pagination.items_per_page.parameter_name%

resource.dummy:
    parent:       api.resource
    arguments:    [ AppBundle\Entity\Dummy, @resource.dummy.data_provider ]

The above use the default parameters specified in the config, to override them is just needed to put the wished value.

But doing so is quite verbose and tedious if one want to do so for several entities. At the moment, the simpliest way I've found is to roll out my own DataProvider, adding some initX methods to play with the parameters and declaring it as abstract. Then I just have to declare a new data provider for my resource using this new data provider as a parent and doing calls to change only the parameters wished:

api.extended_data_provider:
    class:    DataProvider\ExtendedDataProvider
    abstract: true
    arguments:
        - @doctrine
        - %api.collection.order%
        - %api.collection.pagination.page_parameter_name%
        - %api.collection.pagination.items_per_page.number%
        - %api.collection.pagination.items_per_page.enable_client_request%
        - %api.collection.pagination.items_per_page.parameter_name%

resource.dummy.data_provider:
    parent: api.extended_data_provider
    calls:
        -   [ initEnableClientRequestItemsPerPage, [ true ] ]
    tags:   [ { name: api.data_provider } ]

resource.dummy:
    parent:       api.resource
    arguments:    [ AppBundle\Entity\Dummy, @resource.dummy.data_provider ]

In both cases I'm quite unhappy with the process: it's too much for such simple task. Would it be possible to add directly those initX methods in the bundle DataProvider? Unless you see another way, that would imply to also add an abstract service, but at least it 1 + 2 does not feel like hacking the bundle and risking to break everything at every change of the bundle DataProvider anymore.

In both cases, since this is a complete and concrete use case, a dedicated documentation should be available.

To recap:

• Dedicated documentation for the four use cases
• Decide on the approach to handle the 1 + 2 use case in a better way

[theofidry]

Goes with #131

[dunglas]

Done in v2.