team-5/API_DOCUMENTATION.md

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:

{
  "name": "My Radio Station",
  "description": "A cool radio station"
}

Response:

{
  "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

    {
      "username": "john_doe",
      "radioStationId": "station123",
      "joinCode": "ABC123"
    }
    

  • With Join Code only

    { "username": "john_doe", "joinCode": "ABC123" }
    

Response:

{
  "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

  { "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

cd backend
./gradlew bootRun

Server runs on port 8080.

Quick Auth Test

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

---