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:**

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

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