The 'page_size' parameter should allow 0 values

[bgaillard]

Hi, we use PhlyRestfully and now Apigility since several years ;-).

We often need to call a Web Service to count a number of entities. The HAL standard and zf-hal allow to get a count very easily using the total_items property of the fetched HAL collection.

For example...

GET https://myserver.com/comments?page=1&page_size=1
{
  "_links": { ... },
  "_embedded": {
    "comments": [ ... ]
  },
  "page_count": 45,
  "page_size": 1,
  "total_items": 45,
  "page": 1
}

Then on the client side its very simple (sample in JS / jQuery here).

$.get(url, function(payload) { console.log(payload.total_items); });

It works, but I think this is "sub-optimal" because the library forbid page_size values equal to 0 (see

zf-hal/src/Collection.php

Line 295 in 7c164ef

if ($size < 1 && $size !== -1) {

).

In our case its has the following consequences

• This forces an additional request in our database to always fetch at least one entity ;
• It increases the size of the returned payload.

So, why the page_size parameter cannot be equal to 0 ? If their are good reasons what the best practices to count entities efficiently with REST / HAL ? If their are no good reasons could it be possible to authorize page_size 0 values ?

Thanks

[Wilt]

To disable pagination, set -1 for page size.

[bgaillard]

@Wilt thanks for your response.

Ok, we can set -1, but i'm not sure, what's the meaning of "disabling pagination" ?

For me, as a developer, disabling pagination means do not take into account any page or page_size and returns all the results (which is obviously not wanted).

So if we suppose we have a userService->fetch($offset = 0, $pageSize = 12) Business Service function IMO enabling pagination implies this call.

$results = $this->userService->fetch($page - 1, $pageSize);

Disabling pagination should be expressed by this call.

$results = $this->userService->fetch($page - 1, PHP_INT_MAX);

So i'm not sure setting -1 is the same thing as asking to fetch absolutly no result with 0.

What I want to be able to do is that.

$results = $this->userService->fetch($page - 1, 0);

Also if we consider the client side call why would it be forbidden to simply call something that GET https://myserver.com/users?page=1&page_size=0 ?

[Wilt]

I get you; so you don't want any items from your collection, but you are only interested in count.

To achieve this you would like to set page_size to 0.

Sounds like an interesting idea, but not sure if this will work.
Did you even try to test what happens if you set 0 or NULL for page size when using a Paginator?
Will it return what you expect/want?

About your last question:

Also if we consider the client side call why would it be forbidden to simply call something that GET https://myserver.com/users?page=1&page_size=0 ?

I think because it didn't seem to make sense at first. But maybe you found a legitimate reason to allow this...

[TomHAnderson]

Have you tried rendering collections off?
https://github.com/zfcampus/zf-hal/blob/master/src/Plugin/Hal.php#L85

[TomHAnderson]

Also, if you want a count just create an RPC to return just that value.

[weierophinney]

This repository has been closed and moved to laminas-api-tools/api-tools-hal; a new issue has been opened at laminas-api-tools/api-tools-hal#6.