Updated changes in api-refactoring
This commit is contained in:
glenneth
Brian O'Reilly
parent
e126426acd
commit
da054c1ab9
|
|
@ -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/<name>= 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/<name>= 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/<path>= to =/api/asteroid/<name>=
|
||||
- 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
|
||||
|
|
@ -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/<endpoint>=
|
||||
|
||||
** New Format
|
||||
=/api/asteroid/<endpoint>=
|
||||
|
||||
* 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
|
||||
Loading…
Reference in New Issue