2025-summer/team-5
12
Fork 0
Code Issues Pull requests Projects Releases Activity
team-5/backend/API_DOCUMENTATION.md

422 lines
8.3 KiB
Markdown
Raw Blame History

# Serena API docs
## Overview
**Base URL:** `http://localhost:8080/api`
## Authentication
The API uses Bearer token authentication. Include the token in the Authorization header:
```
Authorization: Bearer <token>
```
### Token Types
- **Owner Token**: Generated when creating a radio station, allows full station management
- **Client Token**: Generated when joining a station, allows participation in the station
## API Endpoints
### Radio Station Management
#### Create Radio Station
#### Get All Radio Stations
#### Get Radio Station by ID
#### Delete Radio Station
### Client Management
#### Connect Client to Station
### Song Queue Management
#### Add Song to Client's Preferred Queue
#### Get Radio Station Queue
#### Get Recommended Queue
## Radio Station Management
#### Create Radio Station
Creates a new radio station and returns an owner token.
**Endpoint:** `POST /radio-stations`
**Request Body:**
```json
{
"name": "My Awesome Station",
"description": "The best music station ever"
}
```
**Response:**
```json
{
"success": true,
"message": "Radio station created successfully",
"data": {
"station": {
"id": "station-uuid",
"name": "My Awesome Station",
"description": "The best music station ever",
"ownerId": "owner-uuid",
"joinCode": "ABC123",
"createdAt": "2025-08-01T10:00:00",
"connectedClients": []
},
"ownerToken": "jwt-token-here",
"message": "Radio station created successfully. Use this token to manage your station."
}
}
```
#### Get All Radio Stations
Retrieves all radio stations. Requires authentication.
**Endpoint:** `GET /radio-stations`
**Response:**
```json
{
"success": true,
"message": "Success",
"data": [
{
"id": "station-uuid",
"name": "Station Name",
"description": "Station Description",
"ownerId": "owner-uuid",
"joinCode": "ABC123",
"createdAt": "2025-08-01T10:00:00",
"connectedClients": []
}
]
}
```
#### Get Radio Station by ID
Retrieves a specific radio station. Requires authentication.
**Endpoint:** `GET /radio-stations/{stationId}`
**Response:**
```json
{
"success": true,
"message": "Success",
"data": {
"id": "station-uuid",
"name": "Station Name",
"description": "Station Description",
"ownerId": "owner-uuid",
"joinCode": "ABC123",
"createdAt": "2025-08-01T10:00:00",
"connectedClients": []
}
}
```
#### Delete Radio Station
Deletes a radio station. Only the station owner can delete it.
**Endpoint:** `DELETE /radio-stations/{stationId}`
**Response:**
```json
{
"success": true,
"message": "Radio station deleted successfully",
"data": null
}
```
### Client Management
#### Connect Client to Station
Connects a client to a radio station using a join code. No authentication required.
**Endpoint:** `POST /clients/connect`
**Request Body (Option 1 - Using station ID and join code):**
```json
{
"username": "john_doe",
"radioStationId": "station-uuid",
"joinCode": "ABC123"
}
```
**Request Body (Option 2 - Using join code only):**
```json
{
"username": "john_doe",
"joinCode": "ABC123"
}
```
**Response:**
```json
{
"success": true,
"message": "Successfully connected to radio station",
"data": {
"client": {
"id": "client-uuid",
"username": "john_doe",
"radioStationId": "station-uuid",
"connectedAt": "2025-08-01T10:00:00"
},
"clientToken": "jwt-token-here",
"message": "Successfully connected to radio station. Use this token for further requests."
}
}
```
### Song Queue Management
#### Add Song to Client's Preferred Queue
Adds a song to a specific client's preferred queue. The frontend can merge track and audio features objects using `const merged = { ...trackObj, ...audioFeaturesObj };`
**Endpoint:** `POST /api/songs/queue`
**Request Body:**
```json
{
"song": {
"id": "4iV5W9uYEdYUVa79Axb7Rh",
"popularity": 85,
"tempo": 120.5,
"danceability": 0.8,
"energy": 0.7,
"valence": 0.6,
"acousticness": 0.1,
"instrumentalness": 0.0,
"liveness": 0.1,
"speechiness": 0.04
},
"clientId": "client-uuid",
"radioStationId": "station-uuid"
}
```
**Response:**
```json
{
"success": true,
"message": "Song added to client's preferred queue successfully",
"data": null
}
```
#### Get Radio Station Queue
Retrieves the main song queue for a radio station. Returns a list of song objects.
**Endpoint:** `GET /api/songs/queue?radioStationId={radioStationId}`
**Query Parameters:**
- `radioStationId` (required): The ID of the radio station
**Response:**
```json
{
"success": true,
"message": "Queue retrieved successfully",
"data": [
{
"id": "4iV5W9uYEdYUVa79Axb7Rh",
"popularity": 85,
"tempo": 120.5,
"danceability": 0.8,
"energy": 0.7,
"valence": 0.6,
"acousticness": 0.1,
"instrumentalness": 0.0,
"liveness": 0.1,
"speechiness": 0.04
},
{
"id": "7ouMYWpwJ422jRcDASZB7P",
"popularity": 78,
"tempo": 95.0,
"danceability": 0.6,
"energy": 0.5,
"valence": 0.8,
"acousticness": 0.3,
"instrumentalness": 0.0,
"liveness": 0.2,
"speechiness": 0.06
}
]
}
```
#### Get Recommended Queue
**Endpoint:** `GET /api/songs/queue/recommended?radioStationId={radioStationId}&currentSongId={currentSongId}`
**Query Parameters:**
- `radioStationId` (required): The ID of the radio station
- `currentSongId` (optional): The ID of the currently playing song for similarity analysis
**Response:**
```json
{
"success": true,
"message": "Recommended queue retrieved successfully",
"data": [
{
"id": "4iV5W9uYEdYUVa79Axb7Rh",
"popularity": 85,
"tempo": 120.5,
"audioFeatures": {
"danceability": 0.8,
"energy": 0.7,
"valence": 0.6,
"acousticness": 0.1,
"instrumentalness": 0.0,
"speechiness": 0.04
}
}
]
}
```
## Error Responses
All error responses follow this format:
```json
{
"success": false,
"message": "Error description",
"data": null
}
```
## Usage Examples
### Creating a Station
```bash
curl -X POST http://localhost:8080/api/radio-stations \
-H "Content-Type: application/json" \
-d '{"name": "My Station", "description": "Great music"}'
```
### Joining a Station
```bash
curl -X POST http://localhost:8080/api/clients/connect \
-H "Content-Type: application/json" \
-d '{"username": "john", "joinCode": "ABC123"}'
```
### Getting All Stations (with authentication)
```bash
curl -X GET "http://localhost:8080/api/radio-stations" \
-H "Authorization: Bearer {token}"
```
### Deleting a Station (owner only)
```bash
curl -X DELETE http://localhost:8080/api/radio-stations/{stationId} \
-H "Authorization: Bearer {ownerToken}"
```
### Adding a Song to Client's Preferred Queue
```bash
curl -X POST http://localhost:8080/api/songs/queue \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {clientToken}" \
-d '{
"song": {
"id": "4iV5W9uYEdYUVa79Axb7Rh",
"popularity": 85,
"tempo": 120.5,
"danceability": 0.8,
"energy": 0.7,
"valence": 0.6,
"acousticness": 0.1,
"instrumentalness": 0.0,
"liveness": 0.1,
"speechiness": 0.04
},
"clientId": "client-uuid",
"radioStationId": "station-uuid"
}'
```
### Getting Radio Station Queue
```bash
curl -X GET "http://localhost:8080/api/songs/queue?radioStationId=station-uuid" \
-H "Authorization: Bearer {token}"
```
## Frontend Integration Notes
### Merging Track and Audio Features
The frontend can easily merge track information with audio features using JavaScript object spread:
```javascript
// Track object from Spotify API
const trackObj = {
id: "4iV5W9uYEdYUVa79Axb7Rh",
popularity: 85,
tempo: 120.5,
};
// Audio features object from Spotify API
const audioFeaturesObj = {
danceability: 0.8,
energy: 0.7,
valence: 0.6,
acousticness: 0.1,
instrumentalness: 0.0,
liveness: 0.1,
speechiness: 0.04,
};
// Merge objects for API request
const merged = { ...trackObj, ...audioFeaturesObj };
```
### Queue Data Structure
The queue endpoints return/accept arrays of song objects. Each song object contains:
- Basic track info (id, popularity, tempo)
- Audio features (danceability, energy, valence, etc.)
- All properties are at the root level (flattened structure)
Reference in a new issue View git blame Copy permalink