thrillwiki_django_no_react/memory-bank/documentation/APIs.md

# API Documentation

## API Overview

### Base Configuration
```python
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_jwt.authentication.JSONWebTokenAuthentication',
        'rest_framework.authentication.SessionAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticated',
    ],
    'DEFAULT_PAGINATION_CLASS': 
        'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
    'DEFAULT_VERSIONING_CLASS': 
        'rest_framework.versioning.AcceptHeaderVersioning',
    'DEFAULT_VERSION': 'v1'
}
```

## Authentication

### JWT Authentication
```http
POST /api/token/
Content-Type: application/json

{
    "username": "user@example.com",
    "[PASSWORD-REMOVED]"
}

Response:
{
    "access": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```

### Token Refresh
```http
POST /api/token/refresh/
Content-Type: application/json

{
    "refresh": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}

Response:
{
    "access": "eyJ0eXAiOiJKV1QiLCJhbGc..."
}
```

## Endpoints

### Parks API

#### List Parks
```http
GET /api/v1/parks/
Authorization: Bearer <token>

Response:
{
    "count": 100,
    "next": "http://api.thrillwiki.com/parks/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Adventure Park",
            "slug": "adventure-park",
            "status": "OPERATING",
            "description": "...",
            "location": {
                "city": "Orlando",
                "state": "FL",
                "country": "USA"
            },
            "ride_count": 25,
            "average_rating": 4.5
        }
    ]
}
```

#### Get Park Detail
```http
GET /api/v1/parks/{slug}/
Authorization: Bearer <token>

Response:
{
    "id": 1,
    "name": "Adventure Park",
    "slug": "adventure-park",
    "status": "OPERATING",
    "description": "...",
    "location": {
        "address": "123 Theme Park Way",
        "city": "Orlando",
        "state": "FL",
        "country": "USA",
        "postal_code": "32819",
        "coordinates": {
            "latitude": 28.538336,
            "longitude": -81.379234
        }
    },
    "owner": {
        "id": 1,
        "name": "Theme Park Corp",
        "verified": true
    },
    "stats": {
        "ride_count": 25,
        "coaster_count": 5,
        "average_rating": 4.5
    },
    "rides": [
        {
            "id": 1,
            "name": "Thrill Coaster",
            "type": "ROLLER_COASTER",
            "status": "OPERATING"
        }
    ]
}
```

### Rides API

#### List Rides
```http
GET /api/v1/parks/{park_slug}/rides/
Authorization: Bearer <token>

Response:
{
    "count": 25,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Thrill Coaster",
            "slug": "thrill-coaster",
            "type": "ROLLER_COASTER",
            "status": "OPERATING",
            "height_requirement": 48,
            "thrill_rating": 5,
            "manufacturer": {
                "id": 1,
                "name": "Coaster Corp"
            }
        }
    ]
}
```

#### Get Ride Detail
```http
GET /api/v1/rides/{ride_slug}/
Authorization: Bearer <token>

Response:
{
    "id": 1,
    "name": "Thrill Coaster",
    "slug": "thrill-coaster",
    "type": "ROLLER_COASTER",
    "status": "OPERATING",
    "description": "...",
    "specifications": {
        "height_requirement": 48,
        "thrill_rating": 5,
        "capacity_per_hour": 1200,
        "track_length": 3000
    },
    "manufacturer": {
        "id": 1,
        "name": "Coaster Corp"
    },
    "designer": {
        "id": 1,
        "name": "John Designer"
    },
    "opening_date": "2020-06-15",
    "stats": {
        "average_rating": 4.8,
        "review_count": 150
    }
}
```

### Reviews API

#### Create Review
```http
POST /api/v1/reviews/
Authorization: Bearer <token>
Content-Type: application/json

{
    "content_type": "ride",
    "object_id": 1,
    "rating": 5,
    "content": "Amazing experience!",
    "media": [
        {
            "type": "image",
            "file": "base64encoded..."
        }
    ]
}

Response:
{
    "id": 1,
    "author": {
        "id": 1,
        "username": "reviewer"
    },
    "rating": 5,
    "content": "Amazing experience!",
    "status": "PENDING",
    "created_at": "2024-02-18T14:30:00Z"
}
```

#### List Reviews
```http
GET /api/v1/rides/{ride_id}/reviews/
Authorization: Bearer <token>

Response:
{
    "count": 150,
    "next": "http://api.thrillwiki.com/rides/1/reviews/?page=2",
    "previous": null,
    "results": [
        {
            "id": 1,
            "author": {
                "id": 1,
                "username": "reviewer"
            },
            "rating": 5,
            "content": "Amazing experience!",
            "created_at": "2024-02-18T14:30:00Z",
            "media": [
                {
                    "type": "image",
                    "url": "https://media.thrillwiki.com/reviews/1/image.jpg"
                }
            ]
        }
    ]
}
```

## Integrations

### Email Service Integration
```http
POST /api/v1/email/send/
Authorization: Bearer <token>
Content-Type: application/json

{
    "template": "review_notification",
    "recipient": "user@example.com",
    "context": {
        "review_id": 1,
        "content": "Amazing experience!"
    }
}

Response:
{
    "status": "sent",
    "message_id": "123abc",
    "sent_at": "2024-02-18T14:30:00Z"
}
```

### Media Processing
```http
POST /api/v1/media/process/
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: [binary data]

Response:
{
    "id": 1,
    "original_url": "https://media.thrillwiki.com/original/image.jpg",
    "processed_url": "https://media.thrillwiki.com/processed/image.jpg",
    "thumbnail_url": "https://media.thrillwiki.com/thumbnails/image.jpg",
    "metadata": {
        "width": 1920,
        "height": 1080,
        "format": "jpeg",
        "size": 1024576
    }
}
```

## API Versioning

### Version Header
```http
Accept: application/json; version=1.0
```

### Version Routes
```python
# urls.py
urlpatterns = [
    path('v1/', include('api.v1.urls')),
    path('v2/', include('api.v2.urls')),
]
```

## Error Handling

### Error Response Format
```json
{
    "error": {
        "code": "validation_error",
        "message": "Invalid input data",
        "details": [
            {
                "field": "rating",
                "message": "Rating must be between 1 and 5"
            }
        ]
    }
}
```

### Common Error Codes
- `authentication_error`: Invalid or missing authentication
- `permission_denied`: Insufficient permissions
- `validation_error`: Invalid input data
- `not_found`: Resource not found
- `rate_limit_exceeded`: Too many requests

## Rate Limiting

### Rate Limit Configuration
```python
REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle'
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/day',
        'user': '1000/day',
        'burst': '20/minute'
    }
}
```

### Rate Limit Headers
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1613664000
```

## API Documentation

### Swagger/OpenAPI
```yaml
openapi: 3.0.0
info:
  title: ThrillWiki API
  version: 1.0.0
paths:
  /parks:
    get:
      summary: List parks
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ParkList'
```

### API Documentation URLs
```python
urlpatterns = [
    path('docs/', include_docs_urls(title='ThrillWiki API')),
    path('schema/', schema_view),
]