[API Request] Return total record count for paginated endpoints

[jeffvli]

Type of change

API tweak

Proposal description

getAlbumList and getAlbumList2 currently supports offset pagination using the size and offset parameter. We are currently restricted to infinitely fetching from the endpoint until the number of albums returned are less than the size specified to reach the end.

Having access to the total item count allows clients to paginate in alternative ways, such as using page buttons or a pre-set infinite list.

The total record count would be dynamically returned based upon all parameters set:

• genre
• fromYear
• toYear
• musicFolderId

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

It can be made optional to return this value so that there will be no performance impact if clients do not require it.

Add an optional parameter to getAlbumList2:
- includeTotalRecordCount -- accepts true or false

Possible methods:

1. Return the total record count in the response as totalRecordCount under the returned object

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "albumList2": {
      "totalRecordCount": 2,
      "album": [
        {
          ...album 1 response
        },
        {
         ...album 2 response
        }
      ]
    }
  }
}

2. Return the total record count in the response headers

As an example, Navidrome uses the response header x-total-count to return the total record count for all paginated endpoints in its internal API. Since there's no current precedent for returning info in response headers for Subsonic API, this is probably less likely option between the two.

Security impacts

No response

Potential issues

Possible performance impact on the server-side since the total number of items will need to be queried on each request.

Alternative solutions

No response

[dweymouth]

I definitely agree with this being made optional in case there are any performance impacts. For basic queries like paginated getAlbumList2 requests I think most servers could implement it with no penalty, but with filtering or searching, it's possible some servers may be able to return data more quickly if totalRecordCount doesn't need to be computed.

[gravelld]

Another client this would be useful in is (as an intermediary) bonob because Sonos (the client) requires a total count.

[lachlan-00]

I'm happy if we just made it optional on the response and no inclusion parameter. I already put the result totals in Ampache responses and think it would be good here. it should also go into artist and song/child responses as well.

To get around large queries i put data totals into the server in a table so we're just reading values instead of reading records.

Another option in other response queries, i get the total results and slice them in the output classes so i can get the total without querying again.

[Tolriq]

As stated on some a few other posts, I do not think adding new parameters to current very limited api is really useful.

We in all cases need new proper endpoints for filtering, sorting and paging.

So IMO we can add the field in the response to simplify things before we build the new endpoints (Anyone can propose BTW) but I do not think we should add the parameter to control it, either the server returns it or not as all OS new fields anyway.

[lachlan-00]

here we go @Tolriq and @jeffvli

#102

[lachlan-00]

i've extended it to offset and count parameters for various types