1  #+TITLE: Asteroid Radio - API Endpoints Reference
  2  #+AUTHOR: Asteroid Radio Development Team
  3  #+DATE: 2025-10-26
  4  
  5  * Overview
  6  
  7  Asteroid Radio provides a comprehensive JSON API built with Radiance's =define-api= framework. All API endpoints return JSON responses and follow RESTful conventions.
  8  
  9  ** Base URL
 10  
 11  All API endpoints are prefixed with =/api/asteroid/=
 12  
 13  ** Authentication
 14  
 15  Protected endpoints require user authentication via session cookies. Unauthenticated requests to protected endpoints will return an error response.
 16  
 17  ** Response Format
 18  
 19  All API responses follow this structure:
 20  
 21  #+BEGIN_SRC json
 22  {
 23    "status": "success" | "error",
 24    "message": "Human-readable message",
 25    "data": { ... }  // Optional, endpoint-specific data
 26  }
 27  #+END_SRC
 28  
 29  * Status Endpoints
 30  
 31  ** GET /api/asteroid/status
 32  
 33  Get server status and system information.
 34  
 35  *** Authentication
 36  Not required
 37  
 38  *** Response
 39  #+BEGIN_SRC json
 40  {
 41    "status": "success",
 42    "server": "asteroid-radio",
 43    "version": "1.0",
 44    "uptime": 3600
 45  }
 46  #+END_SRC
 47  
 48  ** GET /api/asteroid/auth-status
 49  
 50  Check current authentication status.
 51  
 52  *** Authentication
 53  Not required
 54  
 55  *** Response
 56  #+BEGIN_SRC json
 57  {
 58    "loggedIn": true,
 59    "username": "admin",
 60    "role": "admin"
 61  }
 62  #+END_SRC
 63  
 64  ** GET /api/asteroid/icecast-status
 65  
 66  Get Icecast streaming server status and current track information.
 67  
 68  *** Authentication
 69  Not required
 70  
 71  *** Response
 72  #+BEGIN_SRC json
 73  {
 74    "icestats": {
 75      "source": {
 76        "title": "Artist - Track Name",
 77        "listeners": 5,
 78        "genre": "Electronic",
 79        "bitrate": 128
 80      }
 81    }
 82  }
 83  #+END_SRC
 84  
 85  * Track Endpoints
 86  
 87  ** GET /api/asteroid/tracks
 88  
 89  Get list of all tracks in the music library.
 90  
 91  *** Authentication
 92  Required
 93  
 94  *** Response
 95  #+BEGIN_SRC json
 96  {
 97    "status": "success",
 98    "tracks": [
 99      {
100        "id": "track-id-123",
101        "title": "Track Name",
102        "artist": "Artist Name",
103        "album": "Album Name",
104        "duration": 245,
105        "format": "mp3"
106      }
107    ]
108  }
109  #+END_SRC
110  
111  ** GET /api/asteroid/admin/tracks
112  
113  Get administrative track listing (admin only).
114  
115  *** Authentication
116  Required (Admin role)
117  
118  *** Response
119  Same as =/api/asteroid/tracks= but includes additional metadata for administration.
120  
121  * Player Control Endpoints
122  
123  ** GET /api/asteroid/player/status
124  
125  Get current player status.
126  
127  *** Authentication
128  Required
129  
130  *** Response
131  #+BEGIN_SRC json
132  {
133    "status": "success",
134    "player": {
135      "state": "playing" | "paused" | "stopped",
136      "currentTrack": {
137        "id": "track-id-123",
138        "title": "Track Name",
139        "artist": "Artist Name"
140      },
141      "position": 45,
142      "duration": 245
143    }
144  }
145  #+END_SRC
146  
147  ** POST /api/asteroid/player/play
148  
149  Play a specific track.
150  
151  *** Authentication
152  Required
153  
154  *** Parameters
155  - =track-id= (required) - ID of the track to play
156  
157  *** Example Request
158  #+BEGIN_SRC bash
159  curl -X POST http://localhost:8080/api/asteroid/player/play \
160    -d "track-id=track-id-123"
161  #+END_SRC
162  
163  *** Response
164  #+BEGIN_SRC json
165  {
166    "status": "success",
167    "message": "Playing track",
168    "player": {
169      "state": "playing",
170      "currentTrack": { ... }
171    }
172  }
173  #+END_SRC
174  
175  ** POST /api/asteroid/player/pause
176  
177  Pause current playback.
178  
179  *** Authentication
180  Required
181  
182  *** Response
183  #+BEGIN_SRC json
184  {
185    "status": "success",
186    "message": "Playback paused",
187    "player": {
188      "state": "paused"
189    }
190  }
191  #+END_SRC
192  
193  ** POST /api/asteroid/player/stop
194  
195  Stop current playback.
196  
197  *** Authentication
198  Required
199  
200  *** Response
201  #+BEGIN_SRC json
202  {
203    "status": "success",
204    "message": "Playback stopped",
205    "player": {
206      "state": "stopped"
207    }
208  }
209  #+END_SRC
210  
211  ** POST /api/asteroid/player/resume
212  
213  Resume paused playback.
214  
215  *** Authentication
216  Required
217  
218  *** Response
219  #+BEGIN_SRC json
220  {
221    "status": "success",
222    "message": "Playback resumed",
223    "player": {
224      "state": "playing"
225    }
226  }
227  #+END_SRC
228  
229  * Playlist Endpoints
230  
231  ** GET /api/asteroid/playlists
232  
233  Get all playlists for the current user.
234  
235  *** Authentication
236  Required
237  
238  *** Response
239  #+BEGIN_SRC json
240  {
241    "status": "success",
242    "playlists": [
243      {
244        "id": "playlist-id-123",
245        "name": "My Playlist",
246        "description": "Favorite tracks",
247        "trackCount": 15,
248        "created": "2025-10-10T12:00:00Z"
249      }
250    ]
251  }
252  #+END_SRC
253  
254  ** POST /api/asteroid/playlists/create
255  
256  Create a new playlist.
257  
258  *** Authentication
259  Required
260  
261  *** Parameters
262  - =name= (required) - Playlist name
263  - =description= (optional) - Playlist description
264  
265  *** Example Request
266  #+BEGIN_SRC bash
267  curl -X POST http://localhost:8080/api/asteroid/playlists/create \
268    -d "name=My Playlist&description=Favorite tracks"
269  #+END_SRC
270  
271  *** Response
272  #+BEGIN_SRC json
273  {
274    "status": "success",
275    "message": "Playlist created successfully",
276    "playlist": {
277      "id": "playlist-id-123",
278      "name": "My Playlist",
279      "description": "Favorite tracks"
280    }
281  }
282  #+END_SRC
283  
284  ** GET /api/asteroid/playlists/get
285  
286  Get details of a specific playlist.
287  
288  *** Authentication
289  Required
290  
291  *** Parameters
292  - =playlist-id= (required) - ID of the playlist
293  
294  *** Example Request
295  #+BEGIN_SRC bash
296  curl "http://localhost:8080/api/asteroid/playlists/get?playlist-id=playlist-id-123"
297  #+END_SRC
298  
299  *** Response
300  #+BEGIN_SRC json
301  {
302    "status": "success",
303    "playlist": {
304      "id": "playlist-id-123",
305      "name": "My Playlist",
306      "description": "Favorite tracks",
307      "tracks": [
308        {
309          "id": "track-id-123",
310          "title": "Track Name",
311          "artist": "Artist Name"
312        }
313      ]
314    }
315  }
316  #+END_SRC
317  
318  ** POST /api/asteroid/playlists/add-track
319  
320  Add a track to a playlist.
321  
322  *** Authentication
323  Required
324  
325  *** Parameters
326  - =playlist-id= (required) - ID of the playlist
327  - =track-id= (required) - ID of the track to add
328  
329  *** Example Request
330  #+BEGIN_SRC bash
331  curl -X POST http://localhost:8080/api/asteroid/playlists/add-track \
332    -d "playlist-id=playlist-id-123&track-id=track-id-456"
333  #+END_SRC
334  
335  *** Response
336  #+BEGIN_SRC json
337  {
338    "status": "success",
339    "message": "Track added to playlist"
340  }
341  #+END_SRC
342  
343  * Admin Endpoints
344  
345  ** POST /api/asteroid/admin/scan-library
346  
347  Scan the music library for new tracks.
348  
349  *** Authentication
350  Required (Admin role)
351  
352  *** Response
353  #+BEGIN_SRC json
354  {
355    "status": "success",
356    "message": "Library scan initiated",
357    "tracksFound": 42
358  }
359  #+END_SRC
360  
361  * Error Responses
362  
363  All endpoints may return error responses in this format:
364  
365  #+BEGIN_SRC json
366  {
367    "status": "error",
368    "message": "Description of the error"
369  }
370  #+END_SRC
371  
372  ** Common HTTP Status Codes
373  
374  - =200= - Success
375  - =400= - Bad Request (missing or invalid parameters)
376  - =401= - Unauthorized (authentication required)
377  - =403= - Forbidden (insufficient permissions)
378  - =404= - Not Found (resource doesn't exist)
379  - =500= - Internal Server Error
380  
381  * Testing API Endpoints
382  
383  ** Using curl
384  
385  #+BEGIN_SRC bash
386  # Get server status
387  curl http://localhost:8080/api/asteroid/status
388  
389  # Get auth status
390  curl http://localhost:8080/api/asteroid/auth-status
391  
392  # Get tracks (requires authentication)
393  curl -b cookies.txt http://localhost:8080/api/asteroid/tracks
394  
395  # Play a track
396  curl -X POST -b cookies.txt http://localhost:8080/api/asteroid/player/play \
397    -d "track-id=123"
398  #+END_SRC
399  
400  ** Using the Test Suite
401  
402  The project includes a comprehensive test suite:
403  
404  #+BEGIN_SRC bash
405  ./test-server.sh
406  #+END_SRC
407  
408  See =docs/TESTING.org= for details.
409  
410  * Browser Detection
411  
412  API endpoints support a =browser= parameter for dual usage (API + browser):
413  
414  #+BEGIN_SRC bash
415  # API usage - returns JSON
416  curl -X POST http://localhost:8080/api/asteroid/playlists/create \
417    -d "name=Test"
418  
419  # Browser usage - redirects to page
420  curl -X POST http://localhost:8080/api/asteroid/playlists/create \
421    -d "name=Test&browser=true"
422  #+END_SRC
423  
424  When =browser=true= is passed, endpoints will redirect to appropriate pages instead of returning JSON.
425  
426  * Rate Limiting
427  
428  API endpoints implement rate limiting to prevent abuse. Excessive requests may result in temporary blocking.
429  
430  * Future Enhancements
431  
432  Planned API improvements:
433  
434  - WebSocket support for real-time updates
435  - Pagination for large result sets
436  - Advanced search and filtering
437  - Batch operations
438  - API versioning
439  - OAuth2 authentication option