Skip to content

Conventions

Pagination

Page-based pagination

Despite including pagination parameters in requests, responses do not include pagination metadata or total element count, as this would impose an additional (and unnecessary) load on the system.

By default, we implement pagination by requesting page by page until the number of items received in a page is less than the requested page size (size parameter).

In the future, if there is a need to know the total number of results in advance for a GET request, a corresponding HEAD method could be implemented to provide this information.

Cursor-based pagination

Unlike the page-based pagination described above, cursor-based pagination uses a reference to the last item returned in the previous page to determine where to continue reading data from.

This approach offers several advantages:

  • Performance efficiency: Cursor-based pagination is more efficient for large datasets as it doesn't require counting the total number of records.
  • Consistency with data changes: Unlike offset pagination, cursor-based pagination provides consistent results even when data is being modified simultaneously.
  • Scalability: This method scales better with large player databases and is less resource-intensive on our backend services.

The client will receive a next_cursor_id parameter in the response that should be passed in the subsequent request to retrieve the next page. Once all data has been retrieved, the has_more field will be set to false indicating no more data is available.

Cached Data

If the response data has been cached, the response will include a last_modified field containing the timestamp when the cached data was generated. This allows clients to determine the freshness of the returned data.

Example

{
    "has_more": true,
    "next_cursor_id": "cursor-id-1234",
    "last_modified": "1970-01-01T00:00:00",
    "data": [
                <object_1>,
                ...,
                <object_n>
              ]
}