From da054c1ab92b0352ca2f0600d71c7d35c53973ff Mon Sep 17 00:00:00 2001 From: glenneth Date: Fri, 10 Oct 2025 05:49:16 +0300 Subject: [PATCH] Updated changes in api-refactoring --- docs/API-REFACTORING-2025-10-08.org | 207 ----------------------- docs/FRONTEND-API-UPDATES-2025-10-08.org | 91 ---------- 2 files changed, 298 deletions(-) delete mode 100644 docs/API-REFACTORING-2025-10-08.org delete mode 100644 docs/FRONTEND-API-UPDATES-2025-10-08.org diff --git a/docs/API-REFACTORING-2025-10-08.org b/docs/API-REFACTORING-2025-10-08.org deleted file mode 100644 index a04cba4..0000000 --- a/docs/API-REFACTORING-2025-10-08.org +++ /dev/null @@ -1,207 +0,0 @@ -#+TITLE: API Endpoint Refactoring - 2025-10-08 -#+AUTHOR: Cascade AI Assistant -#+DATE: 2025-10-08 - -* Overview - -Successfully refactored all API endpoints to use Radiance's built-in =define-api= macro following the framework's best practices and conventions. - -** What Changed -- ✅ All API endpoints now use =define-api= (15 endpoints converted) -- ✅ Web pages still use =define-page= (correct usage for rendering HTML) -- ✅ Static file serving still uses =define-page= (correct usage) - -** Separation of Concerns -- =define-api= → Used for all JSON API endpoints (data access) -- =define-page= → Used for HTML page rendering and static file serving - -** Radiance's =define-api= Pattern - -Radiance's =define-api= signature: -#+BEGIN_SRC lisp -(define-api name (lambda-list) (options) body...) -#+END_SRC - -Key features: -- API endpoints are accessed at =/api/= automatically -- Parameters are specified in lambda-list (required and optional) -- Uses =api-output= function for responses -- Supports browser detection via =(post/get "browser")= for dual user/API usage -- Automatic JSON serialization based on configured API format - -* Changes Made - -** Converted Endpoints to Radiance's =define-api= - -All API endpoints have been refactored from =define-page= with manual JSON handling to proper =define-api= definitions. - -*** Admin API Endpoints -- =asteroid/admin/scan-library= → =/api/asteroid/admin/scan-library= -- =asteroid/admin/tracks= → =/api/asteroid/admin/tracks= - -*** Playlist API Endpoints -- =asteroid/playlists= → =/api/asteroid/playlists= -- =asteroid/playlists/create= (params: name, description) → =/api/asteroid/playlists/create= -- =asteroid/playlists/add-track= (params: playlist-id, track-id) → =/api/asteroid/playlists/add-track= -- =asteroid/playlists/get= (param: playlist-id) → =/api/asteroid/playlists/get= - -*** Track API Endpoints -- =asteroid/tracks= → =/api/asteroid/tracks= - -*** Player Control API Endpoints -- =asteroid/player/play= (param: track-id) → =/api/asteroid/player/play= -- =asteroid/player/pause= → =/api/asteroid/player/pause= -- =asteroid/player/stop= → =/api/asteroid/player/stop= -- =asteroid/player/resume= → =/api/asteroid/player/resume= -- =asteroid/player/status= → =/api/asteroid/player/status= - -*** Status API Endpoints -- =asteroid/auth-status= → =/api/asteroid/auth-status= -- =asteroid/status= → =/api/asteroid/status= -- =asteroid/icecast-status= → =/api/asteroid/icecast-status= - -** Pages Still Using =define-page= (Correct Usage) - -These continue to use =define-page= because they render HTML pages or serve files: - -*** HTML Pages -- =front-page= - Main landing page (/) -- =admin= - Admin dashboard (/admin) -- =users-management= - User management page (/admin/user) -- =user-profile= - User profile page (/profile) -- =register= - Registration page (/register) -- =player= - Web player page (/player) - -*** File Serving -- =static= - Static file serving (/static/*) -- =stream-track= - Audio file streaming (/tracks/*/stream) - -*** Helper Functions -- =api-get-track-by-id= - Internal track lookup (not a public endpoint) - -* Benefits - -1. **Framework Compliance**: Now following Radiance's recommended patterns and best practices -2. **Automatic Routing**: Endpoints automatically available at =/api/= without manual URI configuration -3. **Parameter Handling**: Clean lambda-list based parameter extraction instead of manual =post-var= calls -4. **Dual Usage**: Built-in support for both programmatic API access and browser-based usage -5. **Cleaner Code**: Uses =api-output= for consistent response formatting -6. **Better Error Handling**: Proper HTTP status codes (404, 500, etc.) for different error conditions -7. **Reduced Boilerplate**: No manual JSON encoding or header setting required - -* Code Examples - -** Before (using =define-page=): -#+BEGIN_SRC lisp -(define-page api-pause #@"/api/pause" () - "Pause current playback" - (setf *player-state* :paused) - (setf (radiance:header "Content-Type") "application/json") - (cl-json:encode-json-to-string - `(("status" . "success") - ("message" . "Playback paused") - ("player" . ,(get-player-status))))) -#+END_SRC - -** After (using Radiance's =define-api=): -#+BEGIN_SRC lisp -(define-api asteroid/player/pause () () - "Pause current playback" - (setf *player-state* :paused) - (api-output `(("status" . "success") - ("message" . "Playback paused") - ("player" . ,(get-player-status))))) -#+END_SRC - -** Example with Parameters: -#+BEGIN_SRC lisp -(define-api asteroid/playlists/create (name &optional description) () - "Create a new playlist" - (require-authentication) - (handler-case - (let* ((user (get-current-user)) - (user-id-raw (gethash "_id" user)) - (user-id (if (listp user-id-raw) (first user-id-raw) user-id-raw))) - (create-playlist user-id name description) - (if (string= "true" (post/get "browser")) - (redirect "/asteroid/") - (api-output `(("status" . "success") - ("message" . "Playlist created successfully"))))) - (error (e) - (api-output `(("status" . "error") - ("message" . ,(format nil "Error: ~a" e))) - :status 500)))) -#+END_SRC - -* Testing Recommendations - -** API Endpoint URLs Changed -All API endpoints now use the new URL structure. Update any frontend code or tests: - -Old format: =/api/tracks= -New format: =/api/asteroid/tracks= - -** Testing Checklist -1. Test all API endpoints with new URLs to ensure proper JSON responses -2. Verify parameter passing works correctly (GET/POST parameters) -3. Test browser detection: Add =browser=true= parameter to test redirect behavior -4. Verify error handling returns proper HTTP status codes (404, 500, etc.) -5. Check that authentication/authorization still works on protected endpoints -6. Test endpoints both programmatically and via browser - -** Example Test Commands -#+BEGIN_SRC bash -# Test auth status -curl http://localhost:8080/api/asteroid/auth-status - -# Test with parameters -curl -X POST http://localhost:8080/api/asteroid/playlists/create \ - -d "name=MyPlaylist&description=Test" - -# Test browser mode (should redirect) -curl -X POST http://localhost:8080/api/asteroid/playlists/create \ - -d "name=MyPlaylist&browser=true" - -# Test player control -curl http://localhost:8080/api/asteroid/player/play?track-id=1 -#+END_SRC - -* Frontend Updates Required - -The frontend JavaScript code needs to be updated to use the new API endpoint URLs: - -** Files to Update -- =static/js/profile.js= - Update API calls for playlists -- =static/js/auth-ui.js= - Update auth-status endpoint -- Any other JavaScript files making API calls - -** Example Changes -#+BEGIN_SRC javascript -// Old -fetch('/api/playlists') - -// New -fetch('/api/asteroid/playlists') -#+END_SRC - -* Migration Notes - -** Breaking Changes -- All API endpoint URLs have changed from =/api/= to =/api/asteroid/= -- Parameters are now passed via GET/POST variables, not URI patterns -- The =asteroid/playlists/get= endpoint now requires =playlist-id= as a parameter instead of URI pattern - -** Backward Compatibility -Consider adding route redirects for old API URLs during transition period: -#+BEGIN_SRC lisp -(define-route old-api-redirect "/api/tracks" () - (redirect "/api/asteroid/tracks")) -#+END_SRC - -* Next Steps - -1. **Update Frontend Code**: Modify all JavaScript files to use new API URLs -2. **Test Thoroughly**: Run through all user workflows to ensure APIs work correctly -3. **Update Documentation**: Update any API documentation for external consumers -4. **Monitor Logs**: Watch for any 404 errors indicating missed endpoint updates -5. **Consider JSON Format**: May want to configure Radiance to use JSON API format instead of default S-expressions diff --git a/docs/FRONTEND-API-UPDATES-2025-10-08.org b/docs/FRONTEND-API-UPDATES-2025-10-08.org deleted file mode 100644 index 050a1cc..0000000 --- a/docs/FRONTEND-API-UPDATES-2025-10-08.org +++ /dev/null @@ -1,91 +0,0 @@ -#+TITLE: Frontend API URL Updates - 2025-10-08 -#+AUTHOR: Cascade AI Assistant -#+DATE: 2025-10-08 - -* Overview - -Updated all frontend JavaScript files to use the new Radiance =define-api= endpoint URLs. - -* URL Changes - -** Old Format -=/asteroid/api/= - -** New Format -=/api/asteroid/= - -* Files Updated - -** auth-ui.js -- =/asteroid/api/auth-status= → =/api/asteroid/auth-status= - -** front-page.js -- =/asteroid/api/icecast-status= → =/api/asteroid/icecast-status= - -** admin.js -- =/asteroid/api/player-status= → =/api/asteroid/player/status= - -** player.js (Multiple Updates) -- =/asteroid/api/tracks= → =/api/asteroid/tracks= -- =/api/play?track-id=${id}= → =/api/asteroid/player/play?track-id=${id}= -- =/asteroid/api/playlists/create= → =/api/asteroid/playlists/create= -- =/asteroid/api/playlists= → =/api/asteroid/playlists= -- =/asteroid/api/playlists/${id}= → =/api/asteroid/playlists/get?playlist-id=${id}= (Note: Changed from URI pattern to query parameter) -- =/asteroid/api/playlists/add-track= → =/api/asteroid/playlists/add-track= -- =/asteroid/api/icecast-status= → =/api/asteroid/icecast-status= - -* Important Changes - -** Playlist Get Endpoint -The playlist retrieval endpoint changed from a URI pattern to a query parameter: - -Old: =GET /asteroid/api/playlists/123= -New: =GET /api/asteroid/playlists/get?playlist-id=123= - -This aligns with Radiance's =define-api= pattern where parameters are passed as GET/POST variables rather than URI patterns. - -* Files Not Updated - -** users.js -This file contains API calls to user management endpoints that don't exist in the backend yet: -- =/asteroid/api/users/stats= -- =/asteroid/api/users= -- =/asteroid/api/users/${id}/role= -- =/asteroid/api/users/${id}/deactivate= -- =/asteroid/api/users/${id}/activate= -- =/asteroid/api/users/create= - -These endpoints will need to be implemented using =define-api= when user management features are added. - -** profile.js -This file contains API calls to user profile endpoints that are currently commented out in the backend: -- =/asteroid/api/user/profile= -- =/asteroid/api/user/listening-stats= -- =/asteroid/api/user/recent-tracks= -- =/asteroid/api/user/top-artists= -- =/asteroid/api/user/export-data= -- =/asteroid/api/user/clear-history= - -These will need to be updated once the profile API endpoints are implemented with =define-api=. - -* Testing Checklist - -- [X] Update auth-ui.js -- [X] Update front-page.js -- [X] Update admin.js -- [X] Update player.js -- [ ] Test authentication flow -- [ ] Test track loading and playback -- [ ] Test playlist creation -- [ ] Test playlist loading (with new query parameter format) -- [ ] Test adding tracks to playlists -- [ ] Test Icecast status updates -- [ ] Implement and test user management APIs -- [ ] Implement and test user profile APIs - -* Next Steps - -1. **Test the Application**: Start the server and test all functionality -2. **Implement Missing APIs**: Create user management and profile APIs using =define-api= -3. **Update Remaining Files**: Once APIs are implemented, update users.js and profile.js -4. **Monitor Console**: Check browser console for any 404 errors indicating missed endpoints