Adding New Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
Adding new endpoints to the MoodTune backend follows a structured, five-step architectural pattern to ensure consistency, type safety, and maintainability. The backend is built using FastAPI and utilizes Pydantic v2 for data validation, providing a clear separation between request handling, business logic, and data persistence.
The development workflow requires developers to define the data structures (schemas) and business logic (services) before exposing the functionality through routers. This modular approach supports the project's core features, such as mood analysis via librosa, Spotify integration, and audio file management.
Sources: CLAUDE.md:1-25, CLAUDE.md:46-52
Standard Implementation Workflow
To maintain the architectural integrity of the FastAPI backend, developers MUST follow this specific order when implementing a new feature or endpoint:
- Schema Definition: Create request/response Pydantic models in
app/schemas/<feature>.py. - Service Logic: Implement business logic in
app/services/<feature>_service.py. - Router Implementation: Define the route in
app/api/v1/<feature>.pyand call the corresponding service. - Router Registration: Include the new router in
app/api/v1/api.pyviaapi_router.include_router(...). - Testing: Write and execute pytest tests in the
tests/directory.
Sources: CLAUDE.md:52-58
Architectural Data Flow
The following diagram illustrates the standard request-response flow for a new endpoint:
The data flow ensures that every request is validated against a Pydantic model before reaching the business logic layer.
Sources: CLAUDE.md:27-44, app/api/v1/catalog.py:23-45
Component Breakdown
1. Pydantic Schemas
Schemas define the "shape" of data for both incoming requests and outgoing responses. All models should utilize Pydantic v2 features, including ConfigDict for attribute mapping.
| Field Type | Usage | Location |
|---|---|---|
| Request Model | Defines expected input (JSON body, Form data) | app/schemas/<feature>.py |
| Response Model | Defines the structured JSON returned to the client | app/schemas/<feature>.py |
from pydantic import BaseModel, ConfigDict
from uuid import UUID
class ExampleResponse(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: UUID
status: str
Sources: CLAUDE.md:73-81, app/schemas/audio_analysis.py:7-14
2. Service Layer
Services house the core business logic, such as audio processing or external API calls (e.g., Spotify). Services should be asynchronous and agnostic of HTTP details like status codes or headers.
- Audio Analysis: Uses
librosato extract features like tempo and energy. - External Integration: Handles communication with Jamendo or Spotify.
Sources: app/services/audio_analysis_service.py:16-30, app/api/v1/catalog.py:30-37
3. API Routers
Routers act as the entry point for specific feature sets. They handle authentication dependencies, call services, and raise HTTP exceptions when necessary.
Implementation Checklist
| Step | Action | Reference File |
|---|---|---|
| Auth | Use Depends(get_current_user) for protected routes | app/api/deps.py |
| Async | Use async def for all handlers and service calls | CLAUDE.md:71-71 |
| Errors | Raise HTTPException with appropriate status codes | CLAUDE.md:66-68 |
| Validation | Use Pydantic Field for constraints (e.g., ge=0.0) | app/schemas/audio_analysis.py:18-28 |
Summary
Adding endpoints to the MoodTune backend requires a service-oriented approach where data validation (Schemas) and logic (Services) are decoupled from the transport layer (Routers). By following the established pattern—Schema, Service, Router, Register, Test—developers ensure that new features integrate seamlessly with the existing audio analysis and authentication infrastructure.