Standardize metadata in the API

[motzel]

I noticed on discord that you are going to make improvements to the API along with breaking changes. Maybe this is a good time to standardize how the API returns metadata?

For example, the /api/leaderboards endpoint returns totalCount with the data itself, while the same operation for /api/players requires an additional request to /api/players/count.

IMO, it would be best if every endpoint that returns more than a single record returns a response in the same format. Sth like this:

{
  data: [...query data, varies by endpoint],
  metadata: {
    total: 100,
    page: 1,
    itemsPerPage: 10,
    ...maybe other metadata, such as filters used in the query
  }
}

Additionally, returning itemsPerPage would allow clients to use this information in the UI without hard-coding this value, making it easier to potentially change the default number of records returned by the API.

Since it can be costly for the database to return totals with every query, additionally a query parameter such as withTotals or similar could be added to such endpoints. API client could specify it only with a first query, or optionally refresh the totals every X queries.

@Umbranoxio What do you think about it?

[Umbranoxio]

I 100% agree and this is planned within the next few days

[kinsi55]

If you're doing breaking changes it might make sense to start versioning the api and leaving old versions accessible for a while so that services built on it don't just break until they are updated

[Umbranoxio]

I agree, but for the next 2 weeks, breaking changes will be happening live, perhaps I'll put a notification on the docs, but after the two weeks everything should stabilize.