glenn
/
asteroid
mirror of https://github.com/glenneth1/asteroid.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
asteroid/docs/API-ENDPOINTS.org

7.7 KiB
Raw Blame History

Asteroid Radio - API Endpoints Reference

Overview

Asteroid Radio provides a comprehensive JSON API built with Radiance's define-api framework. All API endpoints return JSON responses and follow RESTful conventions.

Base URL

All API endpoints are prefixed with /api/asteroid/

Authentication

Protected endpoints require user authentication via session cookies. Unauthenticated requests to protected endpoints will return an error response.

Response Format

All API responses follow this structure:

{
  "status": "success" | "error",
  "message": "Human-readable message",
  "data": { ... }  // Optional, endpoint-specific data
}

Status Endpoints

GET /api/asteroid/status

Get server status and system information.

Authentication

Not required

Response 

{
  "status": "success",
  "server": "asteroid-radio",
  "version": "1.0",
  "uptime": 3600
}

GET /api/asteroid/auth-status

Check current authentication status.

Authentication

Not required

Response 

{
  "loggedIn": true,
  "username": "admin",
  "role": "admin"
}

GET /api/asteroid/icecast-status

Get Icecast streaming server status and current track information.

Authentication

Not required

Response 

{
  "icestats": {
    "source": {
      "title": "Artist - Track Name",
      "listeners": 5,
      "genre": "Electronic",
      "bitrate": 128
    }
  }
}

Track Endpoints

GET /api/asteroid/tracks

Get list of all tracks in the music library.

Authentication

Required

Response 

{
  "status": "success",
  "tracks": [
    {
      "id": "track-id-123",
      "title": "Track Name",
      "artist": "Artist Name",
      "album": "Album Name",
      "duration": 245,
      "format": "mp3"
    }
  ]
}

GET /api/asteroid/admin/tracks

Get administrative track listing (admin only).

Authentication

Required (Admin role)

Response

Same as /api/asteroid/tracks but includes additional metadata for administration.

Player Control Endpoints

GET /api/asteroid/player/status

Get current player status.

Authentication

Required

Response 

{
  "status": "success",
  "player": {
    "state": "playing" | "paused" | "stopped",
    "currentTrack": {
      "id": "track-id-123",
      "title": "Track Name",
      "artist": "Artist Name"
    },
    "position": 45,
    "duration": 245
  }
}

POST /api/asteroid/player/play

Play a specific track.

Authentication

Required

Parameters

  • track-id (required) - ID of the track to play

Example Request 

curl -X POST http://localhost:8080/api/asteroid/player/play \
  -d "track-id=track-id-123"

Response 

{
  "status": "success",
  "message": "Playing track",
  "player": {
    "state": "playing",
    "currentTrack": { ... }
  }
}

POST /api/asteroid/player/pause

Pause current playback.

Authentication

Required

Response 

{
  "status": "success",
  "message": "Playback paused",
  "player": {
    "state": "paused"
  }
}

POST /api/asteroid/player/stop

Stop current playback.

Authentication

Required

Response 

{
  "status": "success",
  "message": "Playback stopped",
  "player": {
    "state": "stopped"
  }
}

POST /api/asteroid/player/resume

Resume paused playback.

Authentication

Required

Response 

{
  "status": "success",
  "message": "Playback resumed",
  "player": {
    "state": "playing"
  }
}

Playlist Endpoints

GET /api/asteroid/playlists

Get all playlists for the current user.

Authentication

Required

Response 

{
  "status": "success",
  "playlists": [
    {
      "id": "playlist-id-123",
      "name": "My Playlist",
      "description": "Favorite tracks",
      "trackCount": 15,
      "created": "2025-10-10T12:00:00Z"
    }
  ]
}

POST /api/asteroid/playlists/create

Create a new playlist.

Authentication

Required

Parameters

  • name (required) - Playlist name
  • description (optional) - Playlist description

Example Request 

curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=My Playlist&description=Favorite tracks"

Response 

{
  "status": "success",
  "message": "Playlist created successfully",
  "playlist": {
    "id": "playlist-id-123",
    "name": "My Playlist",
    "description": "Favorite tracks"
  }
}

GET /api/asteroid/playlists/get

Get details of a specific playlist.

Authentication

Required

Parameters

  • playlist-id (required) - ID of the playlist

Example Request 

curl "http://localhost:8080/api/asteroid/playlists/get?playlist-id=playlist-id-123"

Response 

{
  "status": "success",
  "playlist": {
    "id": "playlist-id-123",
    "name": "My Playlist",
    "description": "Favorite tracks",
    "tracks": [
      {
        "id": "track-id-123",
        "title": "Track Name",
        "artist": "Artist Name"
      }
    ]
  }
}

POST /api/asteroid/playlists/add-track

Add a track to a playlist.

Authentication

Required

Parameters

  • playlist-id (required) - ID of the playlist
  • track-id (required) - ID of the track to add

Example Request 

curl -X POST http://localhost:8080/api/asteroid/playlists/add-track \
  -d "playlist-id=playlist-id-123&track-id=track-id-456"

Response 

{
  "status": "success",
  "message": "Track added to playlist"
}

Admin Endpoints

POST /api/asteroid/admin/scan-library

Scan the music library for new tracks.

Authentication

Required (Admin role)

Response 

{
  "status": "success",
  "message": "Library scan initiated",
  "tracksFound": 42
}

Error Responses

All endpoints may return error responses in this format:

{
  "status": "error",
  "message": "Description of the error"
}

Common HTTP Status Codes

  • 200 - Success
  • 400 - Bad Request (missing or invalid parameters)
  • 401 - Unauthorized (authentication required)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (resource doesn't exist)
  • 500 - Internal Server Error

Testing API Endpoints

Using curl 

# Get server status
curl http://localhost:8080/api/asteroid/status

# Get auth status
curl http://localhost:8080/api/asteroid/auth-status

# Get tracks (requires authentication)
curl -b cookies.txt http://localhost:8080/api/asteroid/tracks

# Play a track
curl -X POST -b cookies.txt http://localhost:8080/api/asteroid/player/play \
  -d "track-id=123"

Using the Test Suite

The project includes a comprehensive test suite:

./test-server.sh

See docs/TESTING.org for details.

Browser Detection

API endpoints support a browser parameter for dual usage (API + browser):

# API usage - returns JSON
curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=Test"

# Browser usage - redirects to page
curl -X POST http://localhost:8080/api/asteroid/playlists/create \
  -d "name=Test&browser=true"

When browser=true is passed, endpoints will redirect to appropriate pages instead of returning JSON.

Rate Limiting

API endpoints implement rate limiting to prevent abuse. Excessive requests may result in temporary blocking.

Future Enhancements

Planned API improvements:

  • WebSocket support for real-time updates
  • Pagination for large result sets
  • Advanced search and filtering
  • Batch operations
  • API versioning
  • OAuth2 authentication option