diff --git a/backend/API_DOCUMENTATION.md b/backend/API_DOCUMENTATION.md index 0617740..5ec2777 100644 --- a/backend/API_DOCUMENTATION.md +++ b/backend/API_DOCUMENTATION.md @@ -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}" +```