API Endpoint: GET /tracks/year/{year}

Relevant source files

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

• app/api.py
• app/database.py
• app/config.py
• app/track.py
• test/test_api.py

The GET /tracks/year/{year} endpoint is a specialized resource within the Spotify API Data Collector designed to retrieve track data filtered by a specific release year. This endpoint serves as a primary interface for users to access the structured metadata collected from the Spotify Web API and persisted in the local SQLite database.

This endpoint is part of a broader FastAPI application that exposes music metadata, including track popularity, album information, and detailed artist statistics. It allows for efficient lookup of historical music data within the supported range of 2020 to 2024.
Sources: app/api.py:102-132, README.md:12-25

Endpoint Specification

The endpoint accepts a path parameter for the year and an optional query parameter to limit the results. It enforces strict validation on the year range to ensure data consistency with the project's collection scope.

Request Parameters

Parameter	Type	Location	Description	Constraints
year	Integer	Path	The release year of the tracks to retrieve.	Minimum: 2020, Maximum: 2024
limit	Integer	Query	Maximum number of tracks to return in the response.	Minimum: 1, Maximum: 1000

Sources: app/api.py:103-107, app/config.py:20

Response Structure

The response is returned as a JSON object containing the requested year, the count of tracks found, and a list of track objects.

{
  "year": 2024,
  "count": 1,
  "tracks": [
    {
      "track_id": "string",
      "track_name": "string",
      "track_popularity": 80,
      "album_name": "string",
      "album_release_date": "2024-01-01",
      "duration_ms": 180000,
      "year": 2024,
      "artist_id": "string",
      "artist_name": "string",
      "artist_followers": 1000000,
      "artist_genres": "pop, rock",
      "artist_popularity": 75
    }
  ]
}

Sources: app/api.py:125-131, app/track.py:10-23

Architecture and Data Flow

The endpoint follows a standard request-response cycle involving the FastAPI router, a database utility layer, and a SQLite backend.

Logical Flow

1. Validation: The application first validates that the year provided in the path is within the allowed range (2020–2024). If not, it raises an HTTPException with status code 400.
2. Database Connection: It retrieves a database connection via get_db().
3. Data Retrieval: It calls the get_tracks_by_year function from the database module.
4. Pagination/Limiting: If a limit is provided, the result list is sliced.
5. Serialization: The data is serialized into the final JSON response.

Sources: app/api.py:117-132, app/database.py:90-93

Sequence Diagram

The following diagram illustrates the interaction between the client, the API, and the database for this specific endpoint:

Database Implementation

The endpoint relies on a specialized SQL query optimized by database indexes. The tracks are ordered by popularity to ensure that the most relevant results are returned first.

SQL Query Logic

The underlying query used by this endpoint is:
SELECT * FROM tracks WHERE year = ? ORDER BY track_popularity DESC

To optimize this operation, the system initializes an index on the year column:
CREATE INDEX IF NOT EXISTS idx_tracks_year ON tracks(year)

Sources: app/database.py:34, app/database.py:92

Data Model

The data returned by this endpoint matches the tracks table schema.

Field	Type	Description
track_id	TEXT	Unique Spotify ID (Primary Key/Unique)
track_name	TEXT	Name of the track
track_popularity	INTEGER	Popularity score (0-100)
year	INTEGER	Release year (Indexed)
artist_name	TEXT	Name of the primary artist

Sources: app/database.py:13-28, README.md:31-45

Testing and Validation

The functionality of the GET /tracks/year/{year} endpoint is verified through automated tests in test/test_api.py. These tests cover valid requests, invalid year ranges, and the application of limits.

• Valid Year Test: Ensures that requesting a year like 2024 returns a 200 status code and data containing that year.
• Invalid Year Test: Verifies that requesting a year outside the range (e.g., 2019) results in a 400 status code.
• Limit Test: Confirms that the limit query parameter correctly restricts the number of tracks returned.

Sources: test/test_api.py:157-184

Summary

The GET /tracks/year/{year} endpoint provides a critical filtering capability for the Spotify API Data Collector. By leveraging SQLite indexes and FastAPI's validation features, it ensures high-performance retrieval of music metadata. The implementation strictly adheres to the project's data scope (2020–2024) and provides a structured response suitable for frontend integration or data analysis.