215 lines
4 KiB
Markdown
215 lines
4 KiB
Markdown
# 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}"
|
|
```
|