Skip to main content

​
Introduction

Beat App’s backend architecture consists of two primary API services that handle music data retrieval and streaming functionality. The services are built on top of YouTube Music’s infrastructure, providing a comprehensive music streaming experience.

​
Base Configuration

All API endpoints are configured through environment variables and use a centralized base URL:
src/constants.js
const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:3000';
const YOUTUBE_API = `${API_URL}/api/youtube`;
const STREAM_API = `${API_URL}/api/stream`;
const PROXY_URL = `${STREAM_API}/proxy?url=`;
​
VITE_API_URL
string
default:"http://localhost:3000"
Base URL for all API services. Configure via environment variable.

​
API Services

​
YouTube API Service

Base URL: ${API_URL}/api/youtube Handles all music metadata operations including:
  • Search functionality (tracks, albums, artists, playlists)
  • Content retrieval (albums, artists, playlists)
  • Discovery features (home feed, explore, charts, new releases)
  • Search suggestions and autocomplete
View YouTube API Documentation

​
Stream API Service

Base URL: ${API_URL}/api/stream Handles media streaming operations including:
  • Audio stream proxying
  • Media URL resolution
  • Stream delivery optimization
View Stream API Documentation

​
Authentication

All API requests require Bearer token authentication. The token is configured through environment variables: 
const HEADERS = { 
  Authorization: `Bearer ${import.meta.env.VITE_YOUTUBE_API_TOKEN}` 
};
​
VITE_YOUTUBE_API_TOKEN
string
required
API authentication token for YouTube Music API access

​
Response Patterns

​
Standard Response Structure

Most API endpoints return data in a consistent wrapper format: 
{
  "data": {
    "items": [...],
    "continuation": "token_for_pagination"
  }
}

​
Pagination

Many endpoints support continuation-based pagination:
  1. Initial request returns continuation token in response
  2. Subsequent requests use /continuation endpoint with token parameter
  3. Empty continuation indicates end of results
const res = await axios.get(`${YOUTUBE_API}/search`, {
  params: { q: 'query', filter: 'SONG' },
  headers: HEADERS
});
const { items, continuation } = res.data.data;

​
Error Handling

All service functions implement graceful error handling:
  • Failed requests return empty arrays or objects
  • No exceptions thrown to client code
  • Errors logged to console in development
try {
  const res = await axios.get(endpoint, { headers: HEADERS });
  return res.data.data || [];
} catch (e) {
  console.error('API error:', e);
  return [];
}

​
Data Models

The API implements several data transformation mappers to normalize YouTube Music responses:

​
Rate Limiting

API rate limits are enforced by the upstream YouTube Music API. Implement appropriate request throttling in your application to avoid service disruption.

​
Next Steps

YouTube API

Explore search and metadata endpoints

Stream API

Learn about audio streaming

Build docs developers (and LLMs) love

Get started for freeTalk to us