API Information

Live API Documentation

The API is fully documented and interactive via Swagger UI. You can test the endpoints, view request schemas, and explore the API live:

Explore Songs Wallah API Documentation

Swagger

Base URL

https://music-apis-eokm.onrender.com

**Note:** Since the app is hosted on Render's free tier, the first request might take 30-60 seconds to "wake up" the server.

Information

1) Identity and Security (Core System)

Here, security is not viewed as an add-on; rather, it serves as the foundation upon which the rest of the application is built.

JWT-based stateless sessions, which eliminate the need for server-side session storage and scale smoothly as traffic increases, are used to handle authentication. After logging in, tokens are generated and verified for each protected request.

SendGrid's email-based OTP validation is used to enforce user verification. Fake or partially created users are eliminated early in the lifecycle because accounts cannot be used until verification is finished.

Expired OTPs are automatically eliminated using native SQL cleanup queries to avoid OTP clutter and needless table growth. This eliminates the need for manual intervention or cron jobs, keeping the verification table lean.

2) Finding & Searching for Music

Instead of using a flat list, the song system is designed to meet real-world discovery needs.

Several criteria can be used to filter songs:

• Name of the artist
• Language
• Category or genre

Combining these filters makes it simple to refine results without using complex query logic.

The API returns streaming-ready data without the need for extra lookups or transformations because each song stores all of its metadata, including duration, ratings, and cloud storage URLs.

For complex filters, the repository layer uses native SQL, which provides consistent performance as the dataset expands.

3) Admin Tools

Administrative functionality is deliberately isolated from standard user workflows.

Admins are provided with dedicated endpoints that allow them to:

• Upload multiple songs in a single batch, making large library updates efficient
• Update song metadata such as ratings, URLs, and categories without requiring re-uploads
• View user profiles and process account deletions through controlled request objects

Admin and user operations do not share endpoint logic. This separation prevents permission leakage and keeps responsibilities clearly defined within the system.

4) Performance & Reliability

Performance and reliability decisions in the system are intentional rather than abstract optimizations.

All request and response payloads are implemented using Java Records, which enforces immutability and minimizes unintended side effects across service boundaries.

Error handling is centralized through a global exception handler. Scenarios such as missing songs, invalid OTPs, or unauthorized access return clear, structured error responses instead of generic server failures.

In cases where ORM-based queries became inefficient or difficult to reason about, native SQL was used deliberately. This improves execution performance and query readability, with the known trade-off of reduced portability—an acceptable compromise for this application.

Overall, the system is designed to scale cleanly without unnecessary architectural complexity.

Database Architecture

The database design for Songs Wallah is built around five core tables, each with a clearly defined responsibility. The schema avoids unnecessary coupling while still supporting performance-heavy queries.

1. Users Table (users)

This table acts as the system’s primary identity source.

• Primary Key: id (Long)
• Public Identifier: public_id (UUID), used in API responses to avoid exposing internal IDs
• Fields: Email, encrypted password, first name, last name, and age
• Verification: email_verification flag to control access

2. Songs Table (song_details)

This table represents the global music catalog.

• Indexing: Optimized for filtering by artist name, category, and language using native SQL
• Metadata: Cloud URL, duration, rating, and public UUID

3. Playlists Table (playlist)

This table manages user-created collections and their visibility.

• Ownership: Linked to users via owner_id
• Privacy: Uses accessibility (PUBLIC / PRIVATE) to control visibility
• Song Mapping: Many-to-many relationship via a join table (e.g., playlist_songs)

4. Favorites Table (favorite)

This table handles personalized user preferences.

• Priority-Based Sorting: Includes a priority column (High, Medium, Low)
• Per