team-5/backend/API_DOCUMENTATION.md

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

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."
  }
}

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