203 lines
6.6 KiB
Markdown
203 lines
6.6 KiB
Markdown
# Music Streaming API
|
|
|
|
A RESTful API for a music streaming service built with FastAPI and SQLite.
|
|
|
|
## Features
|
|
|
|
- User authentication (register, login, JWT tokens)
|
|
- Music management (songs, albums, artists)
|
|
- Playlist creation and management
|
|
- Music streaming
|
|
- Search functionality
|
|
- Basic recommendation system
|
|
- File uploads for audio and images
|
|
|
|
## Tech Stack
|
|
|
|
- **FastAPI**: High-performance web framework for building APIs
|
|
- **SQLite**: Lightweight relational database
|
|
- **SQLAlchemy**: SQL toolkit and Object-Relational Mapper
|
|
- **Alembic**: Database migration tool
|
|
- **Pydantic**: Data validation and settings management
|
|
- **JWT**: JSON Web Tokens for authentication
|
|
- **Uvicorn**: ASGI server for hosting the application
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
/
|
|
├── alembic/ # Database migration scripts
|
|
├── app/ # Application source code
|
|
│ ├── api/ # API endpoints
|
|
│ │ ├── deps.py # API dependencies
|
|
│ │ └── v1/ # API version 1
|
|
│ │ ├── api.py # Main API router
|
|
│ │ └── endpoints/ # API endpoint modules
|
|
│ ├── core/ # Core modules
|
|
│ │ ├── config.py # Configuration settings
|
|
│ │ └── security.py # Security utilities
|
|
│ ├── db/ # Database
|
|
│ │ ├── init_db.py # Database initialization
|
|
│ │ └── session.py # Database session
|
|
│ ├── models/ # SQLAlchemy models
|
|
│ ├── schemas/ # Pydantic models/schemas
|
|
│ ├── services/ # Business logic services
|
|
│ └── utils/ # Utility functions
|
|
├── storage/ # Storage for files
|
|
│ ├── db/ # Database files
|
|
│ └── media/ # Media files (audio, images)
|
|
├── main.py # Application entry point
|
|
├── alembic.ini # Alembic configuration
|
|
└── requirements.txt # Python dependencies
|
|
```
|
|
|
|
## Setup and Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd music-streaming-api
|
|
```
|
|
|
|
2. Create virtual environment (optional):
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
3. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. Set up environment variables (create a `.env` file in the root directory):
|
|
```
|
|
SECRET_KEY=your-secret-key
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=11520 # 8 days
|
|
```
|
|
|
|
5. Run database migrations:
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
6. Initialize the database (creates admin user):
|
|
```bash
|
|
# Access the endpoint or run the Python script
|
|
curl http://localhost:8000/init-db
|
|
```
|
|
|
|
7. Start the server:
|
|
```bash
|
|
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
The API is organized into the following groups:
|
|
|
|
### Authentication
|
|
- `POST /api/v1/auth/register` - Register a new user
|
|
- `POST /api/v1/auth/login` - Login to get access token
|
|
- `GET /api/v1/auth/me` - Get current user information
|
|
|
|
### Users
|
|
- `GET /api/v1/users/` - List users (admin only)
|
|
- `POST /api/v1/users/` - Create a new user (admin only)
|
|
- `GET /api/v1/users/me` - Get current user
|
|
- `PUT /api/v1/users/me` - Update current user
|
|
- `GET /api/v1/users/{user_id}` - Get a specific user
|
|
- `PUT /api/v1/users/{user_id}` - Update a user (admin only)
|
|
- `DELETE /api/v1/users/{user_id}` - Delete a user (admin only)
|
|
|
|
### Artists
|
|
- `GET /api/v1/artists/` - List artists
|
|
- `POST /api/v1/artists/` - Create a new artist (admin only)
|
|
- `GET /api/v1/artists/{artist_id}` - Get a specific artist
|
|
- `PUT /api/v1/artists/{artist_id}` - Update an artist (admin only)
|
|
- `DELETE /api/v1/artists/{artist_id}` - Delete an artist (admin only)
|
|
|
|
### Albums
|
|
- `GET /api/v1/albums/` - List albums
|
|
- `POST /api/v1/albums/` - Create a new album (admin only)
|
|
- `GET /api/v1/albums/{album_id}` - Get a specific album
|
|
- `PUT /api/v1/albums/{album_id}` - Update an album (admin only)
|
|
- `DELETE /api/v1/albums/{album_id}` - Delete an album (admin only)
|
|
|
|
### Songs
|
|
- `GET /api/v1/songs/` - List songs
|
|
- `POST /api/v1/songs/` - Create a new song (admin only)
|
|
- `GET /api/v1/songs/{song_id}` - Get a specific song
|
|
- `PUT /api/v1/songs/{song_id}` - Update a song (admin only)
|
|
- `DELETE /api/v1/songs/{song_id}` - Delete a song (admin only)
|
|
|
|
### Playlists
|
|
- `GET /api/v1/playlists/` - List user's playlists
|
|
- `GET /api/v1/playlists/public` - List public playlists
|
|
- `POST /api/v1/playlists/` - Create a new playlist
|
|
- `GET /api/v1/playlists/{playlist_id}` - Get a specific playlist
|
|
- `PUT /api/v1/playlists/{playlist_id}` - Update a playlist
|
|
- `DELETE /api/v1/playlists/{playlist_id}` - Delete a playlist
|
|
- `POST /api/v1/playlists/{playlist_id}/songs` - Add a song to a playlist
|
|
- `DELETE /api/v1/playlists/{playlist_id}/songs` - Remove a song from a playlist
|
|
|
|
### Streaming
|
|
- `GET /api/v1/stream/song/{song_id}` - Stream a song
|
|
- `GET /api/v1/stream/album/cover/{album_id}` - Get album cover image
|
|
- `GET /api/v1/stream/artist/image/{artist_id}` - Get artist image
|
|
|
|
### Upload
|
|
- `POST /api/v1/upload/song` - Upload a song file (admin only)
|
|
- `POST /api/v1/upload/image` - Upload an image file (admin only)
|
|
|
|
### Recommendations
|
|
- `GET /api/v1/recommendations/similar-songs/{song_id}` - Get similar songs
|
|
- `GET /api/v1/recommendations/for-user` - Get personalized recommendations
|
|
- `GET /api/v1/recommendations/popular` - Get popular songs
|
|
- `GET /api/v1/recommendations/similar-artists/{artist_id}` - Get similar artists
|
|
|
|
### Other
|
|
- `GET /health` - Health check endpoint
|
|
- `GET /init-db` - Initialize the database with an admin user
|
|
|
|
## API Documentation
|
|
|
|
Once the application is running, you can access the API documentation at:
|
|
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| SECRET_KEY | Secret key for JWT tokens | Auto-generated |
|
|
| ACCESS_TOKEN_EXPIRE_MINUTES | Minutes before JWT token expires | 11520 (8 days) |
|
|
|
|
## Default Admin User
|
|
|
|
When the database is initialized, a default admin user is created:
|
|
- Email: admin@example.com
|
|
- Username: admin
|
|
- Password: adminpassword
|
|
|
|
It's recommended to change the password immediately after first login in a production environment.
|
|
|
|
## Development
|
|
|
|
### Running Tests
|
|
```bash
|
|
# To be implemented
|
|
pytest
|
|
```
|
|
|
|
### Database Migrations
|
|
To create a new migration after changing models:
|
|
```bash
|
|
alembic revision --autogenerate -m "Description of changes"
|
|
alembic upgrade head
|
|
```
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License. |