# API Architecture Enforcement Rules

## CRITICAL: Centralized API Structure
All API endpoints MUST be centralized under the `backend/api/v1/` structure. This is NON-NEGOTIABLE.

### Mandatory API Directory Structure
```
backend/
├── api/
│   ├── __init__.py
│   ├── urls.py               # Main API router
│   └── v1/
│       ├── __init__.py
│       ├── urls.py           # V1 API routes
│       ├── rides/
│       │   ├── __init__.py
│       │   ├── urls.py       # Ride-specific routes
│       │   ├── views.py      # Ride API views
│       │   └── serializers.py
│       ├── parks/
│       │   ├── __init__.py
│       │   ├── urls.py
│       │   ├── views.py
│       │   └── serializers.py
│       └── auth/
│           ├── __init__.py
│           ├── urls.py
│           ├── views.py
│           └── serializers.py
```

### FORBIDDEN: App-Level API Endpoints
**ABSOLUTELY PROHIBITED:**
- `backend/apps/{app_name}/api_urls.py`
- `backend/apps/{app_name}/api_views.py`
- Any API endpoints defined within individual app directories
- Direct URL routing from apps that bypass the central API structure

### Required URL Pattern
- **Frontend requests:** `/api/{endpoint}` 
- **Vite proxy rewrites to:** `/api/v1/{endpoint}`
- **Django serves from:** `backend/apps/api/v1/{endpoint}`

### Migration Requirements
When consolidating rogue API endpoints:

1. **BEFORE REMOVAL:** Ensure ALL functionality exists in `backend/apps/api/v1/`
2. **Move views:** Transfer all API views to appropriate `backend/apps/api/v1/{domain}/views.py`
3. **Move serializers:** Transfer to `backend/apps/api/v1/{domain}/serializers.py`
4. **Update URLs:** Consolidate routes in `backend/apps/api/v1/{domain}/urls.py`
5. **Test thoroughly:** Verify all endpoints work via central API
6. **Only then remove:** Delete the rogue `api_urls.py` and `api_views.py` files

### Enforcement Actions
If rogue API files are discovered:

1. **STOP all other work**
2. **Create the proper API structure first**
3. **Migrate ALL functionality**
4. **Test extensively** 
5. **Remove rogue files only after verification**

### URL Routing Rules
- **Main API router:** `backend/apps/api/urls.py` includes `apps/api/v1/urls.py`
- **Version router:** `backend/apps/api/v1/urls.py` includes domain-specific routes
- **Domain routers:** `backend/api/v1/{domain}/urls.py` defines actual endpoints
- **No direct app routing:** Apps CANNOT define their own API URLs

### Frontend Integration
- **API client:** `frontend/src/services/api.ts` uses `/api/` prefix
- **Vite proxy:** Automatically rewrites `/api/` to `/api/v1/`
- **URL consistency:** All frontend API calls follow this pattern

### Quality Assurance
- **No API endpoints** may exist outside `backend/apps/api/v1/`
- **All API responses** must use proper DRF serializers
- **Consistent error handling** across all endpoints
- **Proper authentication** and permissions on all routes

### Examples of Proper Structure
```python
# backend/apps/api/urls.py
from django.urls import path, include

urlpatterns = [
    path('v1/', include('api.v1.urls')),
]

# backend/apps/api/v1/urls.py
from django.urls import path, include

urlpatterns = [
    path('rides/', include('api.v1.rides.urls')),
    path('parks/', include('api.v1.parks.urls')),
    path('auth/', include('api.v1.auth.urls')),
]

# backend/apps/api/v1/rides/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path('', views.RideListAPIView.as_view(), name='ride_list'),
    path('filter-options/', views.FilterOptionsAPIView.as_view(), name='filter_options'),
    path('search/companies/', views.CompanySearchAPIView.as_view(), name='search_companies'),
]
```

### CRITICAL FAILURE MODES TO PREVENT
- **Split API responsibility** between apps and central API
- **Inconsistent URL patterns** breaking frontend routing
- **Vite proxy bypass** causing 404 errors
- **Missing functionality** during migration
- **Breaking changes** without proper testing

This rule ensures clean, maintainable, and predictable API architecture that supports the frontend proxy system and prevents the exact issues we discovered in the rides filtering system.