FastAPI Setup & Overview

Relevant source files

The following files were used as context for generating this wiki page:

• app/api.py
• app/main.py
• README.md
• app/config.py
• test/test_api.py
• app/db.py
• app/track.py

The FastAPI component serves as the presentation layer of the Spotify API Data Collector system. Its primary purpose is to expose music metadata collected from Spotify and stored in a local SQLite database through a RESTful interface. This allows external clients to query tracks by year, artist, or popularity, and view aggregate statistics of the collected data.

The API is designed with modularity in mind, separating the web server logic in app/api.py from the database management in app/db.py and the data models in app/track.py. It integrates with the broader system by providing a read-only interface to the data generated by the crawler and data processor components.

Sources: app/api.py:1-12, README.md:1-15

System Architecture & Lifecycle

The API follows a standard FastAPI structure where the application instance is configured with metadata and lifecycle events.

Initialization and Startup

When the API starts, it triggers a startup event. This event is critical for ensuring the database infrastructure is ready before any requests are processed. It invokes init_db() to create the necessary tables and indexes (such as year, artist_name, and track_popularity) if they do not already exist.

Configuration

The API relies on a centralized configuration class that manages environment variables, including database URLs and operational limits.

Parameter	Type	Default	Description
DATABASE_URL	String	sqlite:///spotify_data.db	Connection string for the SQLite database
TRACKS_PER_YEAR	Integer	1000	Max tracks to crawl per year
TOP_N_TRACKS	Integer	200	Number of top popular tracks to retain

Sources: app/config.py:14-23

API Endpoints & Data Flow

The API provides several endpoints for data retrieval and system health monitoring. Data flows from the SQLite database, through the app.database utility functions, and is then filtered or paginated within the API routes.

Endpoint Summary

Method	Endpoint	Description	Key Parameters
GET	/	Root info & endpoints	None
GET	/tracks	List all tracks	limit, offset, year, min_popularity
GET	/tracks/year/{year}	Tracks for a specific year	year, limit
GET	/tracks/artist/{name}	Tracks by artist name	artist_name, limit
GET	/stats	Global statistics	None
GET	/health	Service health status	None

Sources: app/api.py:42-167, README.md:92-120

Retrieval Logic

For the /tracks endpoint, the API loads data using load_tracks_from_db() and applies Python-side filtering for attributes like year and min_popularity. For more specific queries, such as artist searches, it calls dedicated database functions like get_tracks_by_artist(db, artist_name).

Data Models

The API represents music data using the Track model. While the database stores full metadata, the API often transforms this into standard JSON responses.

Track Structure

The following fields are managed within the system and exposed via the API:

• Identifiers: track_id (Spotify ID), artist_id.
• Track Metadata: track_name, track_popularity (0-100), duration_ms, year.
• Album Info: album_name, album_release_date.
• Artist Info: artist_name, artist_followers, artist_genres (comma-separated), artist_popularity.

Sources: app/track.py:7-22, README.md:37-52

Statistics and Analytics

The /stats endpoint provides a high-level overview of the collected dataset. It calculates metrics on-the-fly from the database content.

• Total Count: Total number of tracks in the system.
• Yearly Distribution: Count of tracks per year (filtered for 2020-2024).
• Top Artistes: The top 10 artists based on the number of tracks present in the database.
• Popularity: The average track_popularity across the entire dataset.

Sources: app/api.py:145-185, test/test_api.py:218-245

Conclusion

The FastAPI implementation provides a robust and well-documented interface for the Spotify Data Collector. By utilizing FastAPI's dependency injection and event system, the project ensures that the database is correctly initialized and that data is served efficiently through paginated and filtered endpoints. This setup allows for easy exploration of the music trends captured by the crawler component.