API Endpoint: GET /stats & /health
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The GET /stats and GET /health endpoints are critical monitoring and reporting components of the Spotify API Data Collector. While the core application focuses on crawling and storing metadata for popular tracks from 2020 to 2024, these endpoints provide real-time insights into the health of the FastAPI service and an analytical summary of the data residing in the SQLite database. Sources: app/api.py:10-14, README.md:1-15
The /health endpoint serves as a simple heartbeat check, confirming the operational status of the web service. Conversely, the /stats endpoint performs on-the-fly aggregation of collected tracks to deliver global metrics, such as total track counts, temporal distribution by year, top-performing artists, and average popularity scores. Sources: app/api.py:173-176, app/api.py:133-143
Detailed Sections
Monitoring Service Health (/health)
The /health endpoint is a lightweight GET request designed for health checks by load balancers or monitoring tools. It returns a JSON object indicating that the service is "healthy" and identifies the service name as "spotify-api". Sources: app/api.py:173-176, test/test_api.py:246-253
The diagram above illustrates the simple request-response flow for checking service availability. Sources: app/api.py:173-176
Data Analytics and Global Statistics (/stats)
The /stats endpoint provides a comprehensive overview of the dataset. It leverages the load_tracks_from_db() function, which interfaces with app.db and app.database to fetch all stored records. Sources: app/api.py:133-138, app/api.py:21-31
Data Flow and Logic
- Database Retrieval: The system calls
get_all_tracks()to load all records from the SQLite database. Sources: app/api.py:28-31 - Aggregation:
- By Year: Iterates through tracks to count occurrences per release year.
- Top Artists: Counts tracks per artist and sorts the top 10 results in descending order.
- Popularity: Calculates the arithmetic mean of the
track_popularityfield across all records. Sources: app/api.py:145-170
The sequence diagram details the process from the initial client request to the internal aggregation logic. Sources: app/api.py:133-170, app/api.py:21-31
Data Structures and Responses
| Endpoint | Method | Response Field | Type | Description |
|---|---|---|---|---|
/health | GET | status | String | Current state (e.g., "healthy"). |
/health | GET | service | String | Identifier (e.g., "spotify-api"). |
/stats | GET | total_tracks | Integer | Total count of tracks in DB. |
/stats | GET | by_year | Object | Map of year (key) to track count (value). |
/stats | GET | top_artists | Array | List of objects containing artist name and count. |
/stats | GET | average_popularity | Float | Mean popularity score rounded to 2 decimals. |
Sources: app/api.py:133-176, test/test_api.py:246-253, test/test_api.py:223-233
Implementation Detail: The Stats Aggregator
The aggregator handles empty database states gracefully. If no tracks are found, it returns a default structure with zeroed values to prevent runtime errors. Sources: app/api.py:140-146
# app/api.py:145-165
# Statistiques par année
by_year = {}
for track in tracks:
year = int(track.get('year', 0))
by_year[year] = by_year.get(year, 0) + 1
# Top artistes (par nombre de tracks)
artist_counts = {}
for track in tracks:
artist = track.get('artist_name', '')
artist_counts[artist] = artist_counts.get(artist, 0) + 1
top_artists = sorted(
artist_counts.items(),
key=lambda x: x[1],
reverse=True
)[:10]
Sources: app/api.py:145-165
Conclusion
The /stats and /health endpoints ensure the Spotify API Data Collector remains transparent and measurable. While /health confirms the system's operational integrity, /stats transforms raw SQLite data into actionable insights, facilitating a high-level understanding of the musical trends captured by the crawler between 2020 and 2024. Sources: app/api.py:133-176, README.md:65-80