update API documentation
This commit is contained in:
parent
883ddba3e9
commit
8b0fef03f5
1 changed files with 13 additions and 368 deletions
|
|
@ -51,9 +51,7 @@ Creates a new radio station and returns an owner token.
|
|||
"joinCode": "ABC123",
|
||||
"createdAt": "2025-08-01T10:00:00",
|
||||
"active": true,
|
||||
"connectedClients": [],
|
||||
"songQueue": [],
|
||||
"currentlyPlaying": null
|
||||
"connectedClients": []
|
||||
},
|
||||
"ownerToken": "jwt-token-here",
|
||||
"message": "Radio station created successfully. Use this token to manage your station."
|
||||
|
|
@ -86,9 +84,7 @@ Retrieves all radio stations. Requires authentication.
|
|||
"joinCode": "ABC123",
|
||||
"createdAt": "2025-08-01T10:00:00",
|
||||
"active": true,
|
||||
"connectedClients": ["client1", "client2"],
|
||||
"songQueue": [],
|
||||
"currentlyPlaying": null
|
||||
"connectedClients": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -114,72 +110,7 @@ Retrieves a specific radio station. Requires authentication.
|
|||
"joinCode": "ABC123",
|
||||
"createdAt": "2025-08-01T10:00:00",
|
||||
"active": true,
|
||||
"connectedClients": [],
|
||||
"songQueue": [],
|
||||
"currentlyPlaying": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Radio Station by Join Code
|
||||
|
||||
Retrieves a radio station using its join code. No authentication required.
|
||||
|
||||
**Endpoint:** `GET /radio-stations/join/{joinCode}`
|
||||
|
||||
**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",
|
||||
"active": true,
|
||||
"connectedClients": [],
|
||||
"songQueue": [],
|
||||
"currentlyPlaying": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Update Radio Station
|
||||
|
||||
Updates a radio station. Only the station owner can update it.
|
||||
|
||||
**Endpoint:** `PUT /radio-stations/{stationId}`
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Updated Station Name",
|
||||
"description": "Updated description"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Radio station updated successfully",
|
||||
"data": {
|
||||
"id": "station-uuid",
|
||||
"name": "Updated Station Name",
|
||||
"description": "Updated description",
|
||||
"ownerId": "owner-uuid",
|
||||
"joinCode": "ABC123",
|
||||
"createdAt": "2025-08-01T10:00:00",
|
||||
"active": true,
|
||||
"connectedClients": [],
|
||||
"songQueue": [],
|
||||
"currentlyPlaying": null
|
||||
"connectedClients": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -247,258 +178,6 @@ Connects a client to a radio station using a join code. No authentication requir
|
|||
}
|
||||
```
|
||||
|
||||
#### Disconnect Client
|
||||
|
||||
Disconnects a client from a station. Only the station owner can disconnect clients.
|
||||
|
||||
**Endpoint:** `DELETE /clients/{clientId}/disconnect`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Client disconnected successfully",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Client Information
|
||||
|
||||
Retrieves information about a specific client. Requires authentication.
|
||||
|
||||
**Endpoint:** `GET /clients/{clientId}`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Success",
|
||||
"data": {
|
||||
"id": "client-uuid",
|
||||
"username": "john_doe",
|
||||
"radioStationId": "station-uuid",
|
||||
"connectedAt": "2025-08-01T10:00:00",
|
||||
"active": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Connected Clients
|
||||
|
||||
Retrieves all clients connected to a radio station. Requires authentication.
|
||||
|
||||
**Endpoint:** `GET /clients/station/{radioStationId}`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Success",
|
||||
"data": [
|
||||
{
|
||||
"id": "client-uuid",
|
||||
"username": "john_doe",
|
||||
"radioStationId": "station-uuid",
|
||||
"connectedAt": "2025-08-01T10:00:00",
|
||||
"active": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Song Management
|
||||
|
||||
#### Add Song to Queue
|
||||
|
||||
Adds a song to the station's queue. Requires authentication.
|
||||
|
||||
**Endpoint:** `POST /radio-stations/{stationId}/songs`
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Bohemian Rhapsody",
|
||||
"artist": "Queen",
|
||||
"album": "A Night at the Opera",
|
||||
"duration": 355,
|
||||
"url": "https://example.com/song.mp3"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Song added to queue successfully",
|
||||
"data": {
|
||||
"id": "song-uuid",
|
||||
"title": "Bohemian Rhapsody",
|
||||
"artist": "Queen",
|
||||
"album": "A Night at the Opera",
|
||||
"duration": 355,
|
||||
"url": "https://example.com/song.mp3",
|
||||
"addedBy": "user-uuid",
|
||||
"addedAt": "2025-08-01T10:00:00",
|
||||
"votes": {},
|
||||
"upvotes": 0,
|
||||
"downvotes": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Song Queue
|
||||
|
||||
Retrieves the current song queue, sorted by score (upvotes - downvotes). Requires authentication.
|
||||
|
||||
**Endpoint:** `GET /radio-stations/{stationId}/songs/queue`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Success",
|
||||
"data": [
|
||||
{
|
||||
"id": "song-uuid",
|
||||
"title": "Bohemian Rhapsody",
|
||||
"artist": "Queen",
|
||||
"album": "A Night at the Opera",
|
||||
"duration": 355,
|
||||
"url": "https://example.com/song.mp3",
|
||||
"addedBy": "user-uuid",
|
||||
"addedAt": "2025-08-01T10:00:00",
|
||||
"votes": {
|
||||
"user1": "UPVOTE",
|
||||
"user2": "DOWNVOTE"
|
||||
},
|
||||
"upvotes": 1,
|
||||
"downvotes": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Currently Playing Song
|
||||
|
||||
Retrieves the currently playing song. Requires authentication.
|
||||
|
||||
**Endpoint:** `GET /radio-stations/{stationId}/songs/current`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Success",
|
||||
"data": {
|
||||
"id": "song-uuid",
|
||||
"title": "Bohemian Rhapsody",
|
||||
"artist": "Queen",
|
||||
"album": "A Night at the Opera",
|
||||
"duration": 355,
|
||||
"url": "https://example.com/song.mp3",
|
||||
"addedBy": "user-uuid",
|
||||
"addedAt": "2025-08-01T10:00:00",
|
||||
"votes": {},
|
||||
"upvotes": 0,
|
||||
"downvotes": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Play Next Song
|
||||
|
||||
Plays the next song from the queue (highest scoring song). Only station owners can control playback.
|
||||
|
||||
**Endpoint:** `POST /radio-stations/{stationId}/songs/next`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Playing next song",
|
||||
"data": {
|
||||
"id": "song-uuid",
|
||||
"title": "Bohemian Rhapsody",
|
||||
"artist": "Queen",
|
||||
"album": "A Night at the Opera",
|
||||
"duration": 355,
|
||||
"url": "https://example.com/song.mp3",
|
||||
"addedBy": "user-uuid",
|
||||
"addedAt": "2025-08-01T10:00:00",
|
||||
"votes": {},
|
||||
"upvotes": 0,
|
||||
"downvotes": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Vote on Song
|
||||
|
||||
Casts a vote (upvote or downvote) on a song. Requires authentication.
|
||||
|
||||
**Endpoint:** `POST /radio-stations/{stationId}/songs/{songId}/vote`
|
||||
|
||||
**Request Body:**
|
||||
|
||||
```json
|
||||
{
|
||||
"voteType": "UPVOTE"
|
||||
}
|
||||
```
|
||||
|
||||
**Vote Types:**
|
||||
|
||||
- `UPVOTE`: Positive vote
|
||||
- `DOWNVOTE`: Negative vote
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Vote recorded successfully",
|
||||
"data": {
|
||||
"id": "song-uuid",
|
||||
"title": "Bohemian Rhapsody",
|
||||
"artist": "Queen",
|
||||
"album": "A Night at the Opera",
|
||||
"duration": 355,
|
||||
"url": "https://example.com/song.mp3",
|
||||
"addedBy": "user-uuid",
|
||||
"addedAt": "2025-08-01T10:00:00",
|
||||
"votes": {
|
||||
"current-user-id": "UPVOTE"
|
||||
},
|
||||
"upvotes": 1,
|
||||
"downvotes": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Remove Vote from Song
|
||||
|
||||
Removes the current user's vote from a song. Requires authentication.
|
||||
|
||||
**Endpoint:** `DELETE /radio-stations/{stationId}/songs/{songId}/vote`
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Vote removed successfully",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
All error responses follow this format:
|
||||
|
|
@ -511,28 +190,9 @@ All error responses follow this format:
|
|||
}
|
||||
```
|
||||
|
||||
### Common HTTP Status Codes
|
||||
|
||||
- `200 OK`: Request successful
|
||||
- `201 Created`: Resource created successfully
|
||||
- `400 Bad Request`: Invalid request data
|
||||
- `401 Unauthorized`: Authentication required or token invalid
|
||||
- `403 Forbidden`: Access denied (e.g., not station owner)
|
||||
- `404 Not Found`: Resource not found
|
||||
|
||||
### Common Error Messages
|
||||
|
||||
- `"User not authenticated"`: Missing or invalid authentication token
|
||||
- `"Radio station not found"`: Station ID or join code not found
|
||||
- `"Only the station owner can..."`: Action requires owner privileges
|
||||
- `"Failed to connect to radio station. Invalid join code or station not found."`: Join code is invalid
|
||||
- `"Client not found"`: Client ID not found
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Creating a Station and Adding Songs
|
||||
|
||||
1. **Create a station:**
|
||||
### Creating a Station
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/radio-stations \
|
||||
|
|
@ -540,18 +200,7 @@ curl -X POST http://localhost:8080/api/radio-stations \
|
|||
-d '{"name": "My Station", "description": "Great music"}'
|
||||
```
|
||||
|
||||
2. **Use the returned owner token for authenticated requests:**
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/radio-stations/{stationId}/songs \
|
||||
-H "Authorization: Bearer {ownerToken}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title": "Song Title", "artist": "Artist", "duration": 180, "url": "http://example.com/song.mp3"}'
|
||||
```
|
||||
|
||||
### Joining a Station and Voting
|
||||
|
||||
1. **Join a station:**
|
||||
### Joining a Station
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/clients/connect \
|
||||
|
|
@ -559,20 +208,16 @@ curl -X POST http://localhost:8080/api/clients/connect \
|
|||
-d '{"username": "john", "joinCode": "ABC123"}'
|
||||
```
|
||||
|
||||
2. **Vote on a song:**
|
||||
### Getting All Stations (with authentication)
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/radio-stations/{stationId}/songs/{songId}/vote \
|
||||
-H "Authorization: Bearer {clientToken}" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"voteType": "UPVOTE"}'
|
||||
curl -X GET "http://localhost:8080/api/radio-stations?activeOnly=true" \
|
||||
-H "Authorization: Bearer {token}"
|
||||
```
|
||||
|
||||
## Notes
|
||||
### Deleting a Station (owner only)
|
||||
|
||||
- Join codes are 6-character alphanumeric strings automatically generated for each station
|
||||
- Songs in the queue are sorted by score (upvotes - downvotes) in descending order
|
||||
- Users can change their vote on a song, but only have one vote per song
|
||||
- Only station owners can control playback (play next song)
|
||||
- Tokens expire after 7 days
|
||||
- The system uses in-memory storage, so data is lost when the server restarts
|
||||
```bash
|
||||
curl -X DELETE http://localhost:8080/api/radio-stations/{stationId} \
|
||||
-H "Authorization: Bearer {ownerToken}"
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue