playchoo-manager-nextjs/API.md

API Endpoints Documentation

Complete API Endpoints Usage Map

🔐 Authentication & Session

/login (POST)

└── token-login/[token]/page.tsx:57

/logout (POST)

├── logout/page.tsx:45
└── components/SessionTimeoutModal.tsx:31

/user/context (GET)

├── claim-credentials/page.tsx:67
├── components/ClaimCredentialsModal.tsx:70
└── contexts/UserSettingsContext.tsx:64

---

👤 User Management

/user/bookings (GET)

├── hooks/usePastBookings.ts:14
├── hooks/useUserBookings.ts:35
└── components/UserBookingsTimeline.tsx:44

/user/default_remote_sport (POST)

└── select-remote/page.tsx:61

/credentials/claim (POST/PATCH)

├── claim-credentials/page.tsx:47
└── components/ClaimCredentialsModal.tsx:50

---

🏢 Remotes/Clubs

/remotes (GET)

├── select-remote/page.tsx:33
├── settings/page.tsx:50
└── components/RemoteSportInfo.tsx:49

---

📅 Court Slots & Availability

/day/[date]/slots/[remote_slug]/[sport_slug] (GET)

└── hooks/useCourtSlots.ts:62
    └── booking/[remote_slug]/[sport_slug]/[date]/page.tsx

---

🎾 Bookings

/booking/[slot_id] (GET/DELETE)

├── booking/slot/[slot_id]/page.tsx:66
└── booking/new/[slot_id]/page.tsx:201

/booking/[remote_slug]/[sport_slug] (POST)

└── booking/new/[slot_id]/page.tsx:263

/booking/[slot_id]/change-positions (POST)

└── utils/bookingDetailUtils.ts:58
    └── booking/slot/[slot_id]/page.tsx
        └── confirmOrderChange()

/booking/[slot_id]/players/[index] (PATCH)

└── utils/bookingDetailUtils.ts
    ├── :105 → cancelRequestGen()
    ├── :146 → rejectRequestGen()
    └── :187 → approveRequestGen()
        └── booking/slot/[slot_id]/page.tsx

---

🤝 Join Requests

/booking/join-request/[slot_id] (POST)

├── utils/joinRequests.ts:5
└── components/CourtSlotCard.tsx:84
    └── booking/[remote_slug]/[sport_slug]/[date]/page.tsx:97

/booking/join-request/pending/[remote_slug]/[sport_slug] (GET)

└── utils/joinRequests.ts:11

/booking/join-request/[request_id]/accept (POST)

└── utils/joinRequests.ts:14
    └── booking/slot/[slot_id]/page.tsx

/booking/join-request/[request_id]/reject (POST)

└── utils/joinRequests.ts:20
    └── booking/slot/[slot_id]/page.tsx

---

🏆 Match Results

/booking/[slot_id]/match/result (POST/PATCH)

├── components/ScoreSubmissionModal.tsx:201
├── components/MatchResultDisplay.tsx:65,81
└── booking/slot/[slot_id]/page.tsx:427

/booking/[slot_id]/match/result/[won] (POST)

└── components/ScoreSubmissionModal.tsx:234

---

🔍 Search & Profiles

/players/search/[remote_slug]/[sport_slug]/[search_text] (GET)

└── components/PartnerSearchModal.tsx:231
    ├── booking/new/[slot_id]/page.tsx
    └── booking/slot/[slot_id]/page.tsx

/[type]/[id]/public/[sportSlug] (GET)

├── components/profile/ProfileView.tsx:144
└── components/PartnerSearchModal.tsx:279,289

---

🆕 Match Type Management

/booking/[slot_id]/match-type (PATCH)

└── booking/slot/[slot_id]/page.tsx:629

/booking/match-type-request/[request_id]/approve (POST)

└── booking/slot/[slot_id]/page.tsx:653

/booking/match-type-request/[request_id]/reject (POST)

└── booking/slot/[slot_id]/page.tsx:675

---

API Architecture Patterns

Component Hierarchy for Booking Management

BookingDetailPage → bookingDetailUtils.ts → API calls
├── confirmOrderChange → /booking/[slot_id]/change-positions
├── Position requests → /booking/[slot_id]/players/[index]
├── Join requests → /booking/join-request/[request_id]/{accept,reject}
├── Score submission → /booking/[slot_id]/match/result
└── Match type changes → /booking/[slot_id]/match-type

Search & Profile Flow

PartnerSearchModal
├── Search: /players/search/[remote_slug]/[sport_slug]/[search_text]
├── Profile fetch: /[type]/[id]/public/[sportSlug]
└── Used by: NewBookingPage, BookingDetailPage

Court Slots & Booking Flow

BookingPage → useCourtSlots → /day/[date]/slots/[remote_slug]/[sport_slug]
NewBookingPage → /booking/[remote_slug]/[sport_slug]
BookingDetailPage → /booking/[slot_id]

User Management Flow

SelectRemotePage → /remotes → /user/default_remote_sport
ClaimCredentialsPage → /credentials/claim → /user/context
LogoutPage → /logout

Notes

• All API calls use the apiFetch utility function which:

  • Extracts locale from window.location.pathname and sends via X-Locale header
  • Automatically adds X-Timezone header with user's timezone
  • Includes session cookies for authentication (credentials: 'include')
  • Handles 401 responses by redirecting to login

• API Path Format: All endpoints are called directly (e.g., /user/bookings, /day/2025-10-22/slots/...)

  • No /api/ prefix needed (removed in Oct 2025 refactor)
  • No /${locale}/ prefix needed (locale sent via header)

• Response Types: Type definitions are in /src/lib/types.ts, but many API responses lack comprehensive TypeScript types. Component-level interfaces may exist (e.g., PlayerProfile in PartnerSearchModal.tsx).

• Recently migrated from Next.js API proxy to direct Python backend (Oct 2025):

  • Removed /api/ prefix from all endpoints
  • Changed /booking/new/[remote_slug]/[sport_slug] → /booking/[remote_slug]/[sport_slug]
  • Changed /booking/[slot_id]/player-position/[position] → /booking/[slot_id]/players/[index]
  • All endpoints now call Python backend directly via apiFetch() utility

Known Issues

Assessment API Mismatch

The frontend calls /assessment/next (POST) in assessmentApi.ts:143, but this endpoint doesn't exist in the Python backend. The backend has:

• /assessment/answer (POST) - Save a single answer
• /assessment/session/<session_id>/continue (GET) - Continue existing session

This may need to be refactored to use the correct backend endpoints or the backend needs to implement /assessment/next.