URL Strategy & Routing
Clean, industry-standard URL patterns that eliminate redundancy and match how major APIs structure their endpoints.
🎯 The Clean URL Decision
Our Implementation
✅ Backend (Clean)
api.altsportsleagues.ai/v1/leagues
No redundant /api/ prefix - subdomain already indicates it's an API
✅ Frontend (Namespace)
altsportsleagues.ai/api/v1/leagues
Keeps /api/ for clear namespace separation in frontend code
What We're Avoiding
❌ api.altsportsleagues.ai/api/v1/leagues
Redundant - "api" appears twice (subdomain + path)
🏆 Industry Standard Patterns
All major APIs follow the clean pattern (no /api/ in path):
Stripe: api.stripe.com/v1/charges
GitHub: api.github.com/repos
OpenAI: api.openai.com/v1/chat/completions
Twilio: api.twilio.com/2010-04-01/Accounts
Notice: None use /api/ in the URL path!
🔄 How The Rewrite Works
The Magic of Vercel Rewrites
Vercel's rewrite happens server-side and is invisible to the browser. The browser thinks all requests are same-origin (altsportsleagues.ai), eliminating CORS complexity!
Rewrite Configuration (vercel.json):
{
"rewrites": [
{
"source": "/api/v1/:path*",
"destination": "https://api.altsportsleagues.ai/v1/:path*"
}
]
}📊 URL Pattern Benefits
Comparison Matrix
| Feature | Clean Pattern | Redundant Pattern |
|---|---|---|
| Readability | ✅ Excellent | ❌ Confusing |
| Industry Standard | ✅ Matches leaders | ❌ Non-standard |
| Frontend Code | ✅ Simple | ⚠️ Same |
| External Docs | ✅ Professional | ❌ Awkward |
| API Versioning | ✅ Clear (v1, v2) | ⚠️ Cluttered |
| CORS Handling | ✅ Same (rewrite) | ✅ Same (rewrite) |
Benefits Summary
- Cleaner URLs - Easier to remember and share
- Professional - Matches industry expectations
- Simpler Backend - Less path nesting
- Better Docs - Cleaner API reference examples
- Future-Proof - Easy to add v2, v3, etc.
🌍 Complete URL Reference
Backend API (api.altsportsleagues.ai)
Base URL: https://api.altsportsleagues.ai
/ ← API info and version
/health ← Health check
/docs ← Swagger UI (FastAPI)
/openapi.json ← OpenAPI 3.0 schema
/v1/leagues ← League operations
/v1/teams ← Team operations
/v1/players ← Player operations
/v1/stats ← Statistics
/v1/predictions ← AI predictions
/tools/* ← MCP tools
/webhooks/* ← Webhook endpointsFrontend (altsportsleagues.ai)
Base URL: https://altsportsleagues.ai
/ ← Homepage
/leagues ← League directory
/leagues/[slug] ← Individual league
/teams ← Team directory
/dashboard ← User dashboard
/onboarding ← League owner onboarding
/api/v1/* ← API calls (rewritten to backend)
/docs ← Redirect to docs.altsportsleagues.aiDocumentation (docs.altsportsleagues.ai)
Base URL: https://docs.altsportsleagues.ai
/ ← Documentation homepage
/getting-started ← Onboarding guides
/architecture ← Architecture docs (you are here!)
/api/reference ← API documentation
/schemas ← Schema explorer
/integrations ← Integration guides
/guides ← How-to guides🔌 API Access Patterns
From Frontend (Browser)
Use relative URLs - goes through Vercel rewrite:
// ✅ RECOMMENDED
const response = await fetch('/api/v1/leagues');
// Browser sees: altsportsleagues.ai/api/v1/leagues
// Actually hits: api.altsportsleagues.ai/v1/leagues
// No CORS issues!From External Consumers
Use direct API URLs - requires CORS configuration:
// ✅ For external apps/partners
const response = await fetch('https://api.altsportsleagues.ai/v1/leagues', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
});From n8n Workflows
Use direct API URLs with authentication:
// HTTP Request Node in n8n
{
"url": "https://api.altsportsleagues.ai/v1/leagues",
"method": "POST",
"headers": {
"Authorization": "Bearer {{$env.API_KEY}}",
"Content-Type": "application/json"
}
}🚀 Migration Impact
Implementation Required: Backend routers need to be updated to use /v1/* instead of /api/v1/*.
See the Deployment Workflow for step-by-step instructions.
Files That Need Updates
- Backend Routers - Change prefix from
/api/v1to/v1 - Frontend Config - Update
vercel.jsonrewrite destination - n8n Workflows - Update HTTP request node URLs
- Documentation - Update API examples (automated)
Estimated Migration Time: ~30 minutes
Risk Level: Low (rollback available)
📚 Related Documentation