220 lines
7.6 KiB
Markdown
220 lines
7.6 KiB
Markdown
# SERENA API
|
||
|
||
## Authentication
|
||
|
||
This system uses JWT-like tokens generated automatically during key actions:
|
||
|
||
- **Creating a radio station** generates an **owner token**.
|
||
- **Joining a radio station** generates a **client token**.
|
||
|
||
All subsequent requests require this token in the `Authorization` header:
|
||
|
||
```
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
### Token Generation Endpoints
|
||
|
||
#### Create Radio Station → Owner Token
|
||
|
||
- **POST** `/api/radio-stations`
|
||
- **No authentication required**
|
||
- **Body**:
|
||
|
||
```json
|
||
{
|
||
"name": "My Radio Station",
|
||
"description": "A cool radio station"
|
||
}
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Radio station created successfully",
|
||
"data": {
|
||
"station": {
|
||
/* station object */
|
||
},
|
||
"ownerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Connect to Radio Station → Client Token
|
||
|
||
- **POST** `/api/clients/connect`
|
||
- **No authentication required**
|
||
- **Body Options**:
|
||
|
||
- With Station ID + Join Code
|
||
|
||
```json
|
||
{
|
||
"username": "john_doe",
|
||
"radioStationId": "station123",
|
||
"joinCode": "ABC123"
|
||
}
|
||
```
|
||
|
||
- With Join Code only
|
||
|
||
```json
|
||
{ "username": "john_doe", "joinCode": "ABC123" }
|
||
```
|
||
|
||
**Response:**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Successfully connected to radio station",
|
||
"data": {
|
||
"client": {
|
||
/* client object */
|
||
},
|
||
"clientToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## API Endpoints
|
||
|
||
### Radio Station Management
|
||
|
||
- **Create Station** – `POST /api/radio-stations` (No auth; returns owner token)
|
||
- **Get All Stations** – `GET /api/radio-stations` (Auth: owner or client)
|
||
|
||
- Optional query param: `activeOnly=true`
|
||
|
||
- **Get by ID** – `GET /api/radio-stations/{stationId}` (Auth required)
|
||
- **Get by Join Code** – `GET /api/radio-stations/join/{joinCode}` (Public)
|
||
- **Update Station** – `PUT /api/radio-stations/{stationId}` (Owner only)
|
||
- **Delete Station** – `DELETE /api/radio-stations/{stationId}` (Owner only)
|
||
|
||
### Client Management
|
||
|
||
- **Connect Client** – `POST /api/clients/connect` (No auth; returns client token)
|
||
- **Disconnect Client** – `DELETE /api/clients/{clientId}/disconnect` (Owner only)
|
||
- **Get Client Info** – `GET /api/clients/{clientId}` (Auth required)
|
||
- **Get Station Clients** – `GET /api/clients/station/{radioStationId}` (Auth required)
|
||
|
||
### Song Management
|
||
|
||
> All endpoints require a valid **owner** or **client** token unless specified.
|
||
|
||
- **Add Song** – `POST /api/radio-stations/{stationId}/songs`
|
||
- **Get Queue** – `GET /api/radio-stations/{stationId}/songs/queue`
|
||
- **Get Current Song** – `GET /api/radio-stations/{stationId}/songs/current`
|
||
- **Play Next Song** – `POST /api/radio-stations/{stationId}/songs/next` (Owner only)
|
||
- **Vote on Song** – `POST /api/radio-stations/{stationId}/songs/{songId}/vote`
|
||
|
||
```json
|
||
{ "voteType": "UPVOTE" }
|
||
```
|
||
|
||
`voteType` can be `"UPVOTE"` or `"DOWNVOTE"`.
|
||
|
||
- **Remove Vote** – `DELETE /api/radio-stations/{stationId}/songs/{songId}/vote`
|
||
|
||
---
|
||
|
||
## Models
|
||
|
||
### RadioStation
|
||
|
||
- `id`, `name`, `description`, `ownerId`, `joinCode`, `createdAt`, `isActive`, `connectedClients`, `songQueue`, `currentlyPlaying`
|
||
|
||
### Song
|
||
|
||
- `id`, `title`, `artist`, `album`, `duration`, `url`, `addedBy`, `addedAt`, `votes`, `upvotes`, `downvotes`
|
||
|
||
### Client
|
||
|
||
- `id`, `username`, `radioStationId`, `connectedAt`, `isActive`
|
||
|
||
---
|
||
|
||
## Authentication & Authorization
|
||
|
||
- **Public**: Join stations via join code, connect clients.
|
||
- **Authenticated User**: Add/vote on songs, view stations, connect to stations.
|
||
- **Station Owner**: Manage station (update/delete), control playback, disconnect clients.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- JWT-based authentication for most operations.
|
||
- Join code–based client connection.
|
||
- Owner-only management (updates, deletes, playback).
|
||
- Song queue sorted by votes.
|
||
- Full CORS support.
|
||
|
||
---
|
||
|
||
## Example Flow
|
||
|
||
1. User registers/logs in → gets JWT.
|
||
2. Owner creates station → gets join code + owner token.
|
||
3. Clients join via join code → get client token.
|
||
4. Authenticated users add/vote on songs.
|
||
5. Owner controls playback & manages station.
|
||
|
||
---
|
||
|
||
## Running the Application
|
||
|
||
```bash
|
||
cd backend
|
||
./gradlew bootRun
|
||
```
|
||
|
||
Server runs on port `8080`.
|
||
|
||
### Quick Auth Test
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/auth/register -H "Content-Type: application/json" -d '{"username":"testuser","password":"password123","email":"test@example.com"}'
|
||
curl -X POST http://localhost:8080/api/auth/login -H "Content-Type: application/json" -d '{"username":"testuser","password":"password123"}'
|
||
curl -X GET http://localhost:8080/api/radio-stations -H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
---
|
||
|
||
### **SERENA API Endpoint Table**
|
||
|
||
| Method | Endpoint | Description | Auth Required | Notes |
|
||
| ---------- | ------------------------------------- | ------------------------ | ------------- | -------------------------- |
|
||
| **POST** | `/api/radio-stations` | Create a radio station | ❌ | Returns **owner token** |
|
||
| **GET** | `/api/radio-stations` | Get all stations | ✅ | `activeOnly=true` optional |
|
||
| **GET** | `/api/radio-stations/{stationId}` | Get station by ID | ✅ | — |
|
||
| **GET** | `/api/radio-stations/join/{joinCode}` | Get station by join code | ❌ | Public lookup |
|
||
| **PUT** | `/api/radio-stations/{stationId}` | Update station | ✅ (Owner) | Owner only |
|
||
| **DELETE** | `/api/radio-stations/{stationId}` | Delete station | ✅ (Owner) | Owner only |
|
||
|
||
#### 👥 **Client Management**
|
||
|
||
| Method | Endpoint | Description | Auth Required | Notes |
|
||
| ---------- | --------------------------------------- | -------------------------- | ------------- | ------------------------ |
|
||
| **POST** | `/api/clients/connect` | Connect to station | ❌ | Returns **client token** |
|
||
| **DELETE** | `/api/clients/{clientId}/disconnect` | Disconnect client | ✅ (Owner) | Owner only |
|
||
| **GET** | `/api/clients/{clientId}` | Get client info | ✅ | — |
|
||
| **GET** | `/api/clients/station/{radioStationId}` | Get all clients in station | ✅ | — |
|
||
|
||
#### 🎵 **Song Management**
|
||
|
||
| Method | Endpoint | Description | Auth Required | Notes |
|
||
| ---------- | ----------------------------------------------------- | -------------------------- | ------------- | --------------------------- |
|
||
| **POST** | `/api/radio-stations/{stationId}/songs` | Add song to queue | ✅ | Client or Owner |
|
||
| **GET** | `/api/radio-stations/{stationId}/songs/queue` | Get song queue | ✅ | Sorted by votes |
|
||
| **GET** | `/api/radio-stations/{stationId}/songs/current` | Get currently playing song | ✅ | — |
|
||
| **POST** | `/api/radio-stations/{stationId}/songs/next` | Play next song | ✅ (Owner) | Moves top song to “current” |
|
||
| **POST** | `/api/radio-stations/{stationId}/songs/{songId}/vote` | Vote on song | ✅ | `voteType`: UPVOTE/DOWNVOTE |
|
||
| **DELETE** | `/api/radio-stations/{stationId}/songs/{songId}/vote` | Remove vote | ✅ | Removes user’s vote |
|
||
|
||
---
|