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

8.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.

Integration Examples

JavaScript/Fetch API 

// Get tracks
fetch('/api/asteroid/tracks')
  .then(response => response.json())
  .then(data => {
    console.log('Tracks:', data.tracks);
  });

// Play a track
fetch('/api/asteroid/player/play', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: 'track-id=123'
})
  .then(response => response.json())
  .then(data => {
    console.log('Now playing:', data.player.currentTrack);
  });

Python 

import requests

# Get server status
response = requests.get('http://localhost:8080/api/asteroid/status')
print(response.json())

# Create playlist (with session)
session = requests.Session()
# ... login first ...
response = session.post(
    'http://localhost:8080/api/asteroid/playlists/create',
    data={'name': 'My Playlist', 'description': 'Test'}
)
print(response.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