394 lines
8.6 KiB
Markdown
394 lines
8.6 KiB
Markdown
# 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
|
|
```bash
|
|
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
|
|
```bash
|
|
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):**
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"name": "Example",
|
|
"created_at": "2026-05-07T...",
|
|
"updated_at": "2026-05-07T..."
|
|
}
|
|
```
|
|
|
|
**Success (list):**
|
|
```json
|
|
[
|
|
{ "id": 1, "name": "Item 1" },
|
|
{ "id": 2, "name": "Item 2" }
|
|
]
|
|
```
|
|
|
|
**Error:**
|
|
```json
|
|
{
|
|
"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
|
|
|