Serving Track Details

Welcome back! In the previous lesson, you learned how to set up a backend for a music player app and serve all track data through a single API endpoint. Now, let’s take the next step: serving details for a single track.

Imagine you are building a music app where users can click on a song to see more information — such as the artist, album, or duration. To make this possible, your backend needs to provide a way to fetch details for just one track at a time. This is a common feature in many apps, and it helps keep things fast and efficient for users.

In this lesson, you will learn how to create an API endpoint that returns the details of a specific track when given its ID.

Before we dive in, let’s quickly remind ourselves how the app and data are set up. You already have a Flask app that loads track data from a JSON file using Pandas. Here’s a short code block to refresh your memory:

import pandas as pd
import os

TRACKS_FILE_PATH = os.path.join(os.path.dirname(__file__), '..', 'static', 'tracks.json')
_tracks_cache = None

def load_tracks_data():
    global _tracks_cache
    if _tracks_cache is not None:
        return _tracks_cache
    if not os.path.exists(TRACKS_FILE_PATH):
        _tracks_cache = pd.DataFrame()
        return _tracks_cache
    try:
        _tracks_cache = pd.read_json(TRACKS_FILE_PATH)
        if 'id' in _tracks_cache.columns:
            _tracks_cache['id'] = _tracks_cache['id'].astype(str)
        return _tracks_cache
    except Exception:
        _tracks_cache = pd.DataFrame()
        return _tracks_cache

This function loads all the track data into a Pandas DataFrame, which makes it easy to search and filter tracks later.

Now, let’s look at how to serve the details for a single track. In Flask, you can create a route with a variable part in the URL, like this:

from src.database import (
    get_all_tracks, get_track_by_id)

@app.route('/api/tracks/<track_id>', methods=['GET'])
def get_track_endpoint(track_id):
    """API endpoint to retrieve a specific track by ID."""
    track = get_track_by_id(track_id)
    
    if track is None:
        return jsonify({"error": f"Track {track_id} not found"}), 404
    
    return jsonify(track)

Here’s what’s happening:

• The route /api/tracks/<track_id> means that when someone visits a URL like /api/tracks/123, Flask will call this function and pass 123 as the track_id.
• The function get_track_by_id(track_id) is used to find the track with the given ID.

Let’s see how get_track_by_id works:

def get_track_by_id(track_id):
    """
    Retrieves a single track by its ID.
    Returns track as dictionary or None if not found.
    """
    tracks_df = get_all_tracks()
    
    if tracks_df.empty:
        return None
    
    # Filter DataFrame by track ID
    track_match = tracks_df[tracks_df['id'] == str(track_id)]
    
    if track_match.empty:
        return None
    
    # Return first match as dictionary
    return track_match.iloc[0].to_dict()

Explanation:

• get_all_tracks() loads all tracks into a DataFrame.
• It checks if the DataFrame is empty. If so, it returns None.
• It filters the DataFrame to find the row where the id matches the given track_id.
• If no match is found, it returns None.
• If a match is found, it converts the row to a dictionary and returns it.

Example Output:
If you visit /api/tracks/track002 and there is a track with ID track002, you might get a response like:

{
  "album": "City Lights",
  "artist": "Groove Rider",
  "energy": 0.6000000000000001,
  "genre": "Funk",
  "id": "track002",
  "mood": "Chill",
  "tempo": 90,
  "title": "Midnight Cruise"
}

It’s important to handle cases where the requested track does not exist. In the endpoint, you see this code:

if track is None:
    return jsonify({"error": f"Track {track_id} not found"}), 404

This does two things:

• Returns a JSON object with an error message.
• Sets the HTTP status code to 404, which means “Not Found.”

Example Output:
If you visit /api/tracks/999 and there is no track with ID 999, you will get:

{
  "error": "Track 999 not found"
}

And the HTTP status code will be 404.

Handling errors like this helps users and other developers know exactly what went wrong.

So far, you’ve seen how to return a single track by its ID. But what if you want to get all tracks by a particular artist?

This is common in music apps — users often tap an artist’s name to explore more of their songs. To support this, let’s add a new function in database.py that filters the dataset based on the artist's name.

def get_tracks_by_artist(artist_name):
    """
    Returns a list of tracks that match the given artist name.
    """
    tracks_df = get_all_tracks()
    if tracks_df.empty:
        return []

    # Filter by artist (case-insensitive)
    filtered = tracks_df[tracks_df['artist'].str.lower() == artist_name.lower()]
    
    return filtered.to_dict(orient='records')

This function:

• Loads all track data.
• Filters rows where the artist column matches the name (ignoring case).
• Returns a list of dictionary objects representing each matching track.

Now let’s create a route in app.py that uses this function:

@app.route('/api/tracks/artist/<artist_name>', methods=['GET'])
def get_tracks_by_artist_endpoint(artist_name):
    """API endpoint to get tracks by a specific artist."""
    tracks = get_tracks_by_artist(artist_name)
    return jsonify(tracks)

Now when visiting /api/tracks/artist/Synth Weaver, we'll have something like:

[
  {
    "id": "track001",
    "title": "Sunrise Melody",
    "artist": "Synth Weaver",
    "album": "Digital Dreams",
    "genre": "Electronic",
    "mood": "Uplifting",
    "tempo": 120,
    "energy": 0.8
  },
  {
    "id": "track005",
    "title": "Neon Skies",
    "artist": "Synth Weaver",
    "album": "Digital Dreams II",
    "genre": "Electronic",
    "mood": "Dreamy",
    "tempo": 100,
    "energy": 0.7
  }
]

Note: If you write curl -s http://localhost:5001/api/tracks/artist/Synth Weaver, The shell will interpet Synth and Weaver as two separate arguments, so curl will only receive http://localhost:5001/api/tracks/artist/Synth. You can solve this by quoting the URL and using %20 for the space: curl -s "http://localhost:5001/api/tracks/artist/Synth%20Weaver"

Now that you've seen how to serve tracks by ID and filter by artist or genre, you're welcome to explore further!

Feel free to add your own functions in database.py — for example, try filtering by mood, energy, or tempo. Just make sure to:

• Implement the filtering logic in database.py
• Create a matching route in app.py
• Test it with a cURL request like:

curl -s http://localhost:5001/api/tracks

This is a great way to get creative and practice building real-world APIs from your own ideas. Have fun experimenting!

In this lesson, you learned how to serve details for a single track using its ID — a crucial feature for any interactive music app.

Then you took it further by:

• Creating a route to filter tracks by artist name, returning all matching songs.
• Seeing how simple it is to build custom filtering logic, like searching by genre or mood.
• Learning how to define new functions in database.py and expose them with new API routes in app.py.
• Testing your endpoints using curl or your browser.

Finally, you were encouraged to try your own ideas: filter by energy, tempo, or anything else in the dataset. Next, you’ll get hands-on practice implementing these features yourself. You’re one step closer to building a fully functional audio experience — let’s keep going!