Improving pagination options for browsing endpoints

OpenSubsonic API extensions
1

Type of change

  • API tweak: Add new parameter or new result fields to actual API endpoints

Proposal description

  1. More of the API endpoints should support pagination, especially getArtists and getMusicDirectory and maybe getGenres too.

  2. Add token-based pagination option alongside existing offset-based pagination.

Backward compatibility impact

These tweaks can be implemented in a way that does not break backward compatibility because they can all be implemented with new options on the request. If the client does not set these new options, the behavior is identical to the existing API spec.

API details

Support token-based pagination in addition to the existing offset-based pagination, at least for random sorts. Currently the offset parameter is useless when calling getAlbumList2 with random sort order, since each call will generate a new random shuffling. getAlbumList2 could accept a new request option pagination-token: <string>. The response includes an additional element like <pagination-token>"a21f35-ade56964-fa23bce352"</pagination-token>.

The token is opaque to the client but encodes the current offset into the list AND maintains a single random sort order across multiple calls to the endpoint. On the first call to the endpoint the client supplies an empty string as the token. A new token for the next request is issued each call. On subsequent calls the client supplies the token that the previous response returned.

Security impacts

N/A

Potential issues

This may require servers to maintain additional internal state about the pagination tokens. There may need to be a way for the client to indicate to the server that it is done using a particular pagination token, so that state may be cleared from the server. Else, the tokens could have an expiration time, so the server can automatically clean up the internal state for a given pagination token if it was not used in a request for the last n minutes. This, though, would require clients to be able to gracefully handle the error of using an expired token.

On second thought, if the server is smart about the token format it may not require the server to maintain any internal state as the token could encode all the needed info. For example, the token returned for a random sort order could encode the seed used for the PRNG as well as the offset into the list.

Alternative solutions

N/A