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

8.3 KiB
Raw Permalink 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:

{
  "name": "My Awesome Station",
  "description": "The best music station ever"
}

Response:

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

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

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

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

{
  "username": "john_doe",
  "radioStationId": "station-uuid",
  "joinCode": "ABC123"
}

Request Body (Option 2 - Using join code only):

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

Response:

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

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

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

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

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

{
  "success": false,
  "message": "Error description",
  "data": null
}

Usage Examples

Creating a Station

curl -X POST http://localhost:8080/api/radio-stations \
  -H "Content-Type: application/json" \
  -d '{"name": "My Station", "description": "Great music"}'

Joining a Station

curl -X POST http://localhost:8080/api/clients/connect \
  -H "Content-Type: application/json" \
  -d '{"username": "john", "joinCode": "ABC123"}'

Getting All Stations (with authentication)

curl -X GET "http://localhost:8080/api/radio-stations" \
  -H "Authorization: Bearer {token}"

Deleting a Station (owner only)

curl -X DELETE http://localhost:8080/api/radio-stations/{stationId} \
  -H "Authorization: Bearer {ownerToken}"

Adding a Song to Client's Preferred Queue

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

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:

// 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)