This is an advance notice for a relatively small stats API breaking change:
This affects the following API endpoints:
/1/stats/artist/<mbid>/listeners/1/stats/release-group/<mbid>/listeners/1/stats/sitewide/artist-map
Those endpoints previously returned the field stats_range int he response body, while other stats endpoints use range instead, which we are standardizing on.
master ← NAME-ASHWANIYADAV:LB-1834-stats-range-consistency
opened 11:55AM - 13 Feb 26 UTC
Fixes https://tickets.metabrainz.org/browse/LB-1834
### What's the problem?
…
Some stats endpoints return the requested time range as `"stats_range"` in the response payload, while most others use `"range"`. This inconsistency makes it confusing for API consumers who have to check which key each endpoint uses.
Specifically, these were the inconsistent ones:
- **`/artist/<mbid>/listeners`** and **`/release-group/<mbid>/listeners`** — returned `"stats_range"` (set in [db/stats.py](cci:7://file://wsl$/Ubuntu/home/ashwaniyadav/listenbrainz-server/listenbrainz/db/stats.py:0:0-0:0))
- **`/sitewide/artist-map`** — returned `"stats_range"` (set directly in the view)
- Several docstrings showed `"stats_range"` in their sample JSON, even though the actual code returned `"range"`
### What does this PR do?
Standardizes everything to `"range"` since that's what the majority of endpoints already use:
1. **[listenbrainz/db/stats.py](cci:7://file://wsl$/Ubuntu/home/ashwaniyadav/listenbrainz-server/listenbrainz/db/stats.py:0:0-0:0)** — Changed `doc["stats_range"]` → `doc["range"]` in [get_entity_listener()](cci:1://file://wsl$/Ubuntu/home/ashwaniyadav/listenbrainz-server/listenbrainz/db/stats.py:99:0-138:15), which fixes both the artist and release-group listener endpoints at once.
2. **[listenbrainz/webserver/views/stats_api.py](cci:7://file://wsl$/Ubuntu/home/ashwaniyadav/listenbrainz-server/listenbrainz/webserver/views/stats_api.py:0:0-0:0)** — Changed the [get_sitewide_artist_map()](cci:1://file://wsl$/Ubuntu/home/ashwaniyadav/listenbrainz-server/listenbrainz/webserver/views/stats_api.py:1685:0-1746:6) response to use `"range"` instead of `"stats_range"`, and fixed 5 docstrings that had incorrect sample JSON.
3. **[listenbrainz/tests/integration/test_stats_api.py](cci:7://file://wsl$/Ubuntu/home/ashwaniyadav/listenbrainz-server/listenbrainz/tests/integration/test_stats_api.py:0:0-0:0)** — Updated 2 test assertions to match the new key name.
### Breaking change note
This is technically a breaking change for consumers of these three specific endpoints who rely on the `"stats_range"` key. However, since the documented behavior (in most endpoints) has always been `"range"`, this brings the actual behavior in line with what most users already expect.
3 Likes