LB-1827: Add payload documentation for year-in-music stats api

[meekhumor]

PR contains a schema update, don't forget to run the update file

Problem

The GET /1/stats/user/{user_name}/year-in-music endpoint is listed in the doc but does not describe the structure of its response payload.

Ticket: LB-1827

Solution

Added a detailed docstring documenting the full response payload structure for the year-in-music stats api. Also included year as a top level property in the payload and updated the default year from 2024 to 2025.

Action

No additional action required after merge.

[Zastai]

The documentation should ideally describe how the payload has changed over the years, not just give one example. And perhaps explicitly warn that the payload can get rather big compared to other endpoints.

And if this PR could also resolve the artist_map/yim_artist_map duplication, that would be even better.

[meekhumor]

The documentation should ideally describe how the payload has changed over the years, not just give one example. And perhaps explicitly warn that the payload can get rather big compared to other endpoints.

hi @Zastai, thanks for pointing this out. The behavior you’re referring to is specific to the legacy GET /1/stats/user/{username}/year-in-music/legacy/{year} endpoint. I’ll update the doc for this endpoint and add a warning about the response size in this PR.

And if this PR could also resolve the artist_map/yim_artist_map duplication, that would be even better.

yes, I’ll address this duplication for the legacy endpoint as well in this PR.

[MonkeyDo]

Thanks for working on this documentation !

Some improvements suggestions and small changes below

[MonkeyDo]

That is incorrect, from 2023 onwards the cover art is not separated in *-coverart mappings, but instead for each track a caa_id and caa_release_mbid is included in track.extension["https://musicbrainz.org/doc/jspf#track"].additional_metadata

[meekhumor]

Ah, my bad

[MonkeyDo]

@amCap1712 There is a duplicate key in the 2022 yim payloads, yim_artist_map duplicates artist_map (I checked, content is the same).
Nothing in the front-end or back-end references this (anymore), how do you feel about running this to clean it up and save some space/bandwidth?

UPDATE statistics.year_in_music
SET data = data - 'yim_artist_map'
WHERE year = 2022 AND data ? 'yim_artist_map';

/me learns about JSONB operators in PG

[meekhumor]

@MonkeyDo done with the changes, thanks!

[MonkeyDo]

Looking good, thanks for the clarifications.

I took the liberty of making a couple of changes to remove the duplicate data, hope you don't mind the intervention.
I tested my script locally on data I copied from the production database, and learned some new SQL in the process.

[MonkeyDo]

@amCap1712 There is a duplicate key in the 2022 yim payloads, yim_artist_map duplicates artist_map (I checked, content is the same). Nothing in the front-end or back-end references this (anymore), how do you feel about running this to clean it up and save some space/bandwidth?

UPDATE statistics.year_in_music
SET data = data - 'yim_artist_map'
WHERE year = 2022 AND data ? 'yim_artist_map';

/me learns about JSONB operators in PG

For the record, I ran this update script on the production DB after extensive local testing.
Duplicate data removed.