Skip to content

API_SUMMARY.md

Latest commit

 

History

History
180 lines (139 loc) · 5.9 KB

API_SUMMARY.md

File metadata and controls

180 lines (139 loc) · 5.9 KB

API Layer Implementation Summary

✅ Completed

The Web API layer has been successfully implemented and is ready for testing.

Project Structure

src/SpotifyTools.Web/
├── Controllers/
│   ├── GenresController.cs       # Genre and genre-track endpoints
│   ├── TracksController.cs       # Track CRUD and search
│   ├── PlaylistsController.cs    # Playlist management
│   └── ClustersController.cs     # Cluster operations
├── DTOs/
│   ├── GenreDto.cs
│   ├── TrackDto.cs
│   ├── ArtistSummaryDto.cs
│   ├── PlaylistDto.cs
│   ├── ClusterDto.cs
│   ├── PagedResult.cs
│   └── CreatePlaylistRequest.cs
├── Program.cs                     # DI configuration, Swagger setup
└── appsettings.json              # Connection strings

API Endpoints Implemented

Genres API (/api/genres)

  • GET /api/genres - List all genres with track/artist counts
  • GET /api/genres/{genreName}/tracks?page=1&pageSize=50 - Paginated tracks for a genre

Tracks API (/api/tracks)

  • GET /api/tracks?page=1&pageSize=50&sortBy=name - Paginated all tracks
  • GET /api/tracks/search?q={query}&page=1&pageSize=50 - Search tracks
  • GET /api/tracks/{id} - Get single track by ID

Playlists API (/api/playlists)

  • GET /api/playlists - List all playlists
  • GET /api/playlists/{id} - Get playlist with tracks
  • POST /api/playlists - Create new playlist
  • POST /api/playlists/{id}/tracks - Add tracks to playlist (bulk)
  • DELETE /api/playlists/{id}/tracks/{trackId} - Remove track from playlist
  • DELETE /api/playlists/{id} - Delete playlist

Clusters API (/api/clusters)

  • GET /api/clusters - List saved clusters
  • GET /api/clusters/{id} - Get cluster by ID
  • GET /api/clusters/suggested?minTracksPerCluster=20 - Generate suggested clusters
  • POST /api/clusters - Save a new cluster
  • PUT /api/clusters/{id} - Update cluster
  • DELETE /api/clusters/{id} - Delete cluster
  • POST /api/clusters/{id}/finalize - Mark cluster as finalized
  • POST /api/clusters/{id}/create-playlist?makePublic=false - Create Spotify playlist from cluster

Key Features

  1. Pagination - All list endpoints support server-side pagination
  2. DTOs - Clean separation between domain entities and API contracts
  3. Swagger/OpenAPI - Auto-generated API documentation at root URL
  4. Dependency Injection - Reuses all existing services (Analytics, Sync, UnitOfWork)
  5. CORS Enabled - Ready for frontend clients
  6. Error Handling - Consistent 500 error responses with logging

Configuration

The API uses the same configuration as the CLI tool:

  • Database: PostgreSQL on localhost:5433
  • Connection string: Defined in appsettings.json
  • Port: Default 5000 (HTTP) / 5001 (HTTPS)

Next Steps

  1. Test the API:

    cd src/SpotifyTools.Web
dotnet run

    Then open browser to https://localhost:5001 for Swagger UI

  2. Sample API Calls:

    # Get all genres
curl https://localhost:5001/api/genres

# Get tracks for a genre (paginated)
curl "https://localhost:5001/api/genres/rock/tracks?page=1&pageSize=20"

# Search tracks
curl "https://localhost:5001/api/tracks/search?q=metallica"

# Get suggested clusters
curl "https://localhost:5001/api/clusters/suggested?minTracksPerCluster=20"

  3. Build Blazor UI (Next phase)

    • Add Razor components for three-panel layout
    • Create ApiClientService for typed HTTP calls
    • Implement virtualized lists with Blazor.Virtualizer

Architecture Highlights

Clean Separation:

Blazor Components → HTTP → API Controllers → Services → Repositories → Database

Same Process Hosting:

  • API and Blazor will run in the same process
  • HTTP calls are in-memory (localhost loopback)
  • Minimal overhead (~1-5ms latency)

Technical Notes

  • All database columns use snake_case (enforced by EFCore.NamingConventions)
  • Artist.Genres is stored as string[] in domain, converted to List in DTOs
  • Playlist entity doesn't have SpotifyId (uses Id field directly)
  • IRepository.Delete is synchronous, not async
  • PagedResult includes HasNextPage/HasPreviousPage helpers

Branch: cop_webui
Status: ✅ Ready for testing
Build: ✅ Compiles successfully

✅ BLAZOR UI ADDED (Jan 3, 2026)

The web UI is now complete with a three-panel layout!

What's Included

  1. Three-Panel Layout (/)

    • Left Panel: Genre list (clickable, shows track counts)
    • Center Panel: Track browser with checkboxes for multi-select
    • Right Panel: Playlist list

  2. ApiClientService - Typed HTTP client for calling the API

  3. Bootstrap 5 - Modern responsive styling

  4. Interactive Features:

    • Click genre → Loads tracks
    • Select tracks with checkboxes
    • Refresh button to reload data

How to Run

cd src/SpotifyTools.Web
dotnet run

Then visit:

Important: If the UI doesn't respond to clicks, do a hard refresh (Shift+Refresh or Cmd+Shift+R on Mac) to clear browser cache and establish the Blazor WebSocket connection.

Current Features (MVP)

✅ View all genres ✅ Browse tracks by genre (click genre to load tracks) ✅ Multi-select tracks with checkboxes ✅ View all playlists
✅ Loading states and spinners ✅ Interactive Blazor Server with SignalR ⏳ Add tracks to playlist (coming next) ⏳ Create new playlists (coming next) ⏳ Drag & drop (future enhancement)

Next Steps

To make it fully functional:

  1. Implement "Add to Playlist" modal with playlist selector
  2. Implement "Create New Playlist" modal
  3. Add playlist detail view (show tracks in selected playlist)
  4. Add virtualization for large track lists (100+ items)
  5. Add search/filter for tracks
  6. Implement drag-drop (optional enhancement)