jukebox/www/api/README_API_DOCS.md

Laravel Jukebox API - Documentation Index

Welcome! This directory contains comprehensive documentation for the Laravel Jukebox API.

📚 Documentation Files

1. API_QUICK_REFERENCE.md ⭐ START HERE

Best for: Quick lookups, endpoint overview, getting oriented

• Database relationship diagram
• Complete endpoint summary (40+ routes)
• Authentication methods
• Validation rules
• Known limitations
• Quick start examples with curl

Read time: ~5 minutes

---

2. API_EXAMPLES.md

Best for: Understanding request/response formats, testing endpoints

• Real request/response examples for every operation
• All CRUD operations demonstrated
• Error response samples
• HTTP status codes reference
• Headers and authentication examples
• cURL command examples

Read time: ~10 minutes

---

3. API_DOCUMENTATION.md

Best for: Complete technical reference, deep understanding

• All API routes with descriptions
• All 8 controllers and 31 methods detailed
• All 7 models with relationships
• Database schema (11 tables) with column details
• Authentication & authorization explained
• Configuration details
• Seeders & factories documentation
• CORS configuration status
• Key observations & recommendations

Read time: ~20 minutes

---

🚀 Quick Start

Step 1: Register a user

curl -X POST http://localhost/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Name",
    "email": "user@example.com",
    "password": "password123",
    "password_confirmation": "password123"
  }'

Step 2: Get your token

The response contains a token field. Copy it.

Step 3: Use the token

curl -X GET http://localhost/api/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Step 4: Explore

Browse the API_EXAMPLES.md for more operations.

---

📊 API Structure

PUBLIC ENDPOINTS (2)
├── POST /register
└── POST /login

AUTHENTICATED ENDPOINTS (37+)
├── Account Management
│   ├── POST /logout
│   └── GET /me
├── User Likes
│   ├── GET /me/likes
│   ├── POST /tracks/{id}/like
│   └── DELETE /tracks/{id}/like
└── Browse (Read-only)
    ├── Labels (GET /labels, /labels/{id})
    ├── Genres (GET /genres, /genres/{id})
    ├── Artists (GET /artists, /artists/{id})
    ├── Albums (GET /albums, /albums/{id})
    └── Tracks (GET /tracks, /tracks/{id})

ADMIN-ONLY ENDPOINTS (24)
├── Create/Update/Delete: Labels, Genres, Artists, Albums, Tracks
└── User Management: List, View, Update, Delete Users

---

🔐 Authentication

This API uses Laravel Sanctum Bearer Tokens.

1. Register or login to get a token
2. Include token in all requests: Authorization: Bearer {token}
3. Tokens stored in personal_access_tokens table
4. No automatic expiration (infinite lifetime)

---

👥 Authorization

Two roles exist:

• user (default) - Can browse content and manage likes
• admin - Can create/update/delete content and manage users

Checked via custom EnsureAdmin middleware.

---

📁 Directory Map

/app
  /Http/Controllers  - 8 controllers with 31 methods
  /Http/Middleware   - EnsureAdmin (role checking)
  /Models            - 7 Eloquent models with relationships

/routes
  /api.php          - All 40+ API routes defined here
  /web.php          - Minimal web routes

/database
  /migrations       - 11 migration files (ordered)
  /seeders          - DatabaseSeeder (creates test user)
  /factories        - UserFactory (only one)

/config
  /sanctum.php      - Token auth configuration
  /auth.php         - Authentication guards setup

---

📋 Database Schema Overview

Core Tables

• roles - User roles (admin, user)
• users - User accounts
• labels - Record labels
• genres - Music genres

Music Catalog

• artists - Musicians/bands
• albums - Albums/EPs/singles
• tracks - Individual songs

Relationships

• artist_track - Many-to-many (artists can have many tracks)
• track_genre - Many-to-many (tracks can have many genres)
• likes - Many-to-many (users can like many tracks)

Authentication

• personal_access_tokens - Sanctum tokens for API authentication

---

🔄 Data Relationships

User
├── role (1-to-many)
└── likes (many-to-many: Track)

Artist
├── label (1-to-many)
└── tracks (many-to-many)

Album
├── label (1-to-many)
└── tracks (1-to-many)

Track
├── album (1-to-many)
├── artists (many-to-many)
├── genres (many-to-many)
└── likedBy users (many-to-many)

Genre
└── tracks (many-to-many)

Label
├── artists (1-to-many)
└── albums (1-to-many)

---

⚠️ Current Limitations

• ❌ No pagination on list endpoints
• ❌ No search/filtering capability
• ❌ No rate limiting
• ❌ No API documentation tool (Swagger/OpenAPI)
• ❌ No automatic response wrapping
• ❌ No audit logging
• ❌ Limited test coverage

See API_DOCUMENTATION.md §11 for detailed observations.

---

🔧 Key Technologies

• Framework: Laravel 13.0
• PHP: 8.3+
• Database: MySQL (Docker at 172.17.0.1:3306)
• Authentication: Laravel Sanctum 4.0
• ORM: Eloquent
• Testing: PHPUnit (12.5.12)

---

📝 Response Format

All responses are JSON.

Success (single resource):

{
  "id": 1,
  "name": "Example",
  "created_at": "2026-05-07T...",
  "updated_at": "2026-05-07T..."
}

Success (list):

[
  { "id": 1, "name": "Item 1" },
  { "id": 2, "name": "Item 2" }
]

Error:

{
  "message": "Error description",
  "errors": {
    "field": ["Validation error message"]
  }
}

---

🧪 Testing Accounts

Test User (from DatabaseSeeder):

• Email: test@example.com
• Password: password
• Role: user

Use these credentials to login and get a token.

---

📞 Common Tasks

Browse Music

GET /api/artists
GET /api/albums
GET /api/tracks

Like/Favorite

POST /api/tracks/{id}/like
GET /api/me/likes
DELETE /api/tracks/{id}/like

Create Content (Admin)

POST /api/artists
POST /api/albums
POST /api/tracks

Manage Users (Admin)

GET /api/users
POST /api/users/{id}
DELETE /api/users/{id}

---

📖 Reading Order Recommendation

1. This file (2 min) - Get oriented
2. API_QUICK_REFERENCE.md (5 min) - See all endpoints
3. API_EXAMPLES.md (10 min) - See request/response examples
4. routes/api.php (5 min) - Read actual route definitions
5. app/Http/Controllers/ (10 min) - Read controller implementations
6. app/Models/ (5 min) - Understand data models
7. API_DOCUMENTATION.md (20 min) - Deep dive on everything

Total time: ~60 minutes for complete understanding

---

🔍 Need More Info?

• Routes: See /routes/api.php - single file with all endpoints
• Controllers: See /app/Http/Controllers/ - one per resource
• Models: See /app/Models/ - Eloquent models with relationships
• Database: See /database/migrations/ - migration files
• Auth: See /config/sanctum.php and /config/auth.php

---

📋 Endpoint Summary

Category	Public	Authenticated	Admin-Only
Auth	2	2	0
Browse	0	10	0
Likes	0	3	0
Labels	0	1	3
Genres	0	1	3
Artists	0	1	3
Albums	0	1	3
Tracks	0	1	3
Users	0	0	4
TOTAL	2	19	19

Total Endpoints: 40+

---

✅ Checklist for Understanding the API

After reading the documentation, you should understand:

• What are the 2 public endpoints?
• How to authenticate (register → login → token)?
• How to use the token in requests?
• The 3 endpoint categories (public, authenticated, admin)?
• All 7 data models and their relationships?
• The database schema and table structure?
• How admin access control works?
• Response format (success and error)?
• HTTP status codes (200, 201, 204, 403, 404, 422)?
• How to like a track and get favorites?

---

🎯 Next Steps

1. For Frontend Integration: Read API_QUICK_REFERENCE.md + API_EXAMPLES.md
2. For Backend Development: Read API_DOCUMENTATION.md thoroughly
3. For Testing: Use test user credentials in API_EXAMPLES.md
4. For Production: Address limitations in API_DOCUMENTATION.md §11

---

Last Updated: May 7, 2026

Documentation Version: 1.0

API Version: Laravel 13 + Sanctum 4

---

Questions?

Refer to the appropriate documentation file:

• Quick question? → API_QUICK_REFERENCE.md
• How do I do X? → API_EXAMPLES.md
• Why is it built this way? → API_DOCUMENTATION.md