ai-stylegallery/prp/api-specification.md

# API Specification

## Overview
RESTful API built with Laravel Sanctum for authentication. Provides endpoints for image management, style application, and AI processing integration.

## Base URL
```
/api
```

## Authentication
Laravel Sanctum token-based authentication using `Authorization: Bearer <token>` header.

## Response Format
All responses use JSON format with consistent structure:

### Success Response
```json
{
  "message": "Operation completed successfully",
  "data": { ... }
}
```

### Error Response
```json
{
  "error": "Error description",
  "message": "Detailed error message"
}
```

## Endpoints

### 1. Image Management

#### 1.1 Get Images
**Endpoint**: `GET /api/images`

**Authentication**: Not required (filtered by visibility rules)

**Description**: Retrieves paginated list of images with automatic filesystem synchronization

**Query Parameters**:
- None

**Response**:
```json
[
  {
    "image_id": 1,
    "path": "/storage/uploads/image.jpg",
    "name": "image.jpg",
    "is_temp": false,
    "is_public": true,
    "is_new": true
  }
]
```

**Business Logic**:
- Synchronizes filesystem with database before returning results
- Filters images based on authentication status
- Adds `is_new` flag for recently uploaded images (within configurable timespan)
- Returns images in descending order by `updated_at`

**Error Codes**:
- `500`: Internal server error during synchronization

---

#### 1.2 Upload Image
**Endpoint**: `POST /api/images/upload`

**Authentication**: Not required

**Description**: Uploads new image file to the gallery

**Request Body** (multipart/form-data):
```json
{
  "image": "file (JPEG, PNG, WebP, max 10MB)"
}
```

**Response**:
```json
{
  "message": "Image uploaded successfully",
  "image_id": 1,
  "path": "/storage/uploads/new-image.jpg"
}
```

**Validation Rules**:
- `image`: required, image file, mime types: jpeg,png,webp, max:10240KB

**Business Logic**:
- Generates unique filename to prevent conflicts
- Stores in `public/storage/uploads/` directory
- Creates database record with `is_public = true`
- Returns full URL path for immediate use

**Error Codes**:
- `422`: Validation failed (invalid file type/size)
- `500`: File storage error

---

#### 1.3 Apply Style to Image
**Endpoint**: `POST /api/images/style-change`

**Authentication**: Not required (same-origin check)

**Description**: Initiates AI style transformation process

**Headers**:
```
Referer: https://yourdomain.com (same-origin validation)
```

**Request Body**:
```json
{
  "image_id": 1,
  "style_id": 1
}
```

**Response**:
```json
{
  "message": "Style change request sent",
  "prompt_id": "comfyui-job-123",
  "image_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "plugin": "comfyui"
}
```

**Validation Rules**:
- `image_id`: required, exists in `images` table
- `style_id`: nullable, exists in `styles` table

**Business Logic**:
- Validates same-origin request for security
- Loads appropriate AI plugin based on style's API provider
- Updates image record with `comfyui_prompt_id` and `style_id`
- Returns tracking information for frontend progress monitoring

**Error Codes**:
- `403`: Unauthorized origin
- `404`: Image or style not found
- `422`: Validation failed
- `500`: Plugin processing error

---

#### 1.4 Fetch Styled Image Result
**Endpoint**: `GET /api/images/fetch-styled/{promptId}`

**Authentication**: Not required

**Description**: Retrieves result of completed AI style transformation

**Path Parameters**:
- `promptId`: string (ComfyUI job identifier)

**Response**:
```json
{
  "message": "Styled image fetched successfully",
  "styled_image": {
    "id": 2,
    "path": "/storage/uploads/styled_image.png",
    "is_temp": true
  }
}
```

**Business Logic**:
- Finds image record by `comfyui_prompt_id`
- Loads appropriate AI plugin to fetch result
- Saves styled image to filesystem
- Creates new database record for styled image
- Links styled image to original via `original_image_id`

**Error Codes**:
- `404`: Image not found or still processing
- `500`: Plugin fetch error or file save error

---

#### 1.5 Keep Styled Image
**Endpoint**: `POST /api/images/keep`

**Authentication**: Required (Sanctum)

**Description**: Converts temporary styled image to permanent

**Request Body**:
```json
{
  "image_id": 2
}
```

**Response**:
```json
{
  "message": "Image kept successfully"
}
```

**Validation Rules**:
- `image_id`: required, exists in `images` table

**Business Logic**:
- Verifies user owns the image
- Sets `is_temp = false` on image record
- Image becomes permanent part of user's gallery

**Error Codes**:
- `401`: Unauthenticated
- `404`: Image not found
- `403`: User doesn't own image

---

#### 1.6 Delete Image
**Endpoint**: `DELETE /api/images/{image}`

**Authentication**: Required (Sanctum)

**Description**: Permanently removes image and file

**Path Parameters**:
- `image`: integer (image ID)

**Response**:
```json
{
  "message": "Image deleted successfully"
}
```

**Business Logic**:
- Verifies user owns the image
- Deletes physical file from storage
- Removes database record
- Cascading: styled images deleted when original is deleted

**Error Codes**:
- `401`: Unauthenticated
- `404`: Image not found
- `403`: User doesn't own image
- `500`: File deletion error

---

#### 1.7 Get Image Status (Deprecated)
**Endpoint**: `GET /api/images/status`

**Authentication**: Not required

**Description**: Legacy endpoint for image processing status

**Query Parameters**:
```json
{
  "image_id": 1,
  "api_provider_name": "ComfyUI"
}
```

**Response**:
```json
{
  "status": "unknown"
}
```

**Note**: Currently returns static response, replaced by WebSocket progress

---

### 2. Style Management

#### 2.1 Get Available Styles
**Endpoint**: `GET /api/styles`

**Authentication**: Not required

**Description**: Retrieves all enabled styles for style selector

**Response**:
```json
[
  {
    "id": 1,
    "title": "Oil Painting",
    "description": "Classic oil painting style",
    "preview_image": "/storage/style_previews/oil-painting.jpg",
    "enabled": true
  }
]
```

**Business Logic**:
- Returns only enabled styles
- Includes preview images for UI display
- Ordered by `sort_order` field

**Error Codes**:
- `500`: Database query error

---

### 3. AI Provider Management

#### 3.1 Get ComfyUI URL
**Endpoint**: `GET /api/comfyui-url`

**Authentication**: Not required

**Description**: Returns WebSocket URL for real-time progress updates

**Query Parameters** (optional):
```json
{
  "style_id": 1,
  "image_uuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Response**:
```json
{
  "comfyui_url": "https://your-comfyui-server.com"
}
```

**Business Logic**:
- Determines appropriate API provider based on style or image
- Falls back to first available ComfyUI provider if none specified
- Returns base URL for WebSocket connection

**Error Codes**:
- `404`: No enabled ComfyUI provider found

---

### 4. User Management

#### 4.1 Get Authenticated User
**Endpoint**: `GET /api/user`

**Authentication**: Required (Sanctum)

**Description**: Returns current authenticated user information

**Response**:
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "theme_preference": "light",
  "locale": "en"
}
```

**Error Codes**:
- `401`: Unauthenticated

---

### 5. Admin Management

#### 5.1 Store Navigation State
**Endpoint**: `POST /api/admin/navigation-state`

**Authentication**: Required (Sanctum)

**Description**: Saves admin panel navigation preferences

**Request Body**:
```json
{
  "state": "collapsed",
  "active_tab": "dashboard"
}
```

**Response**:
```json
{
  "message": "Navigation state saved"
}
```

**Business Logic**:
- Stores UI state preferences for admin users
- Used by Filament admin panel for user experience

---

## WebSocket Integration

### ComfyUI Progress Updates

**Connection**:
```
WebSocket URL: ws://{comfyui-server-host}/ws
```

**Message Format**:
```json
{
  "type": "progress",
  "data": {
    "prompt_id": "job-123",
    "value": 50,
    "max": 100
  }
}
```

**Frontend Handling**:
- Connect to WebSocket after receiving `prompt_id` from style-change endpoint
- Monitor progress messages for matching `prompt_id`
- Update UI progress bar based on `value/max` percentage
- Fetch final result when progress reaches 100%

## Error Handling

### HTTP Status Codes
- `200`: Success
- `201`: Created
- `400`: Bad Request
- `401`: Unauthenticated
- `403`: Forbidden
- `404`: Not Found
- `422`: Validation Error
- `500`: Internal Server Error

### Error Response Structure
```json
{
  "error": "Human readable error message",
  "message": "Technical details for debugging",
  "errors": {
    "field_name": ["Specific field validation errors"]
  }
}
```

## Rate Limiting

### Current Implementation
- No explicit rate limiting configured
- External AI services may have their own limits
- Consider implementing for production deployment

### Recommended Limits
- Image upload: 10 per minute per user
- Style change requests: 5 per minute per user
- API calls: 1000 per hour per user

## Security Considerations

### Authentication
- Laravel Sanctum for API authentication
- Bearer token in Authorization header
- CSRF protection for web routes

### Input Validation
- All inputs validated using Laravel Form Requests
- File upload restrictions (type, size)
- SQL injection prevention via Eloquent ORM

### Same-Origin Policy
- Style change endpoint validates request origin
- Prevents CSRF attacks from external sites

### File Security
- Uploaded files stored outside web root
- File type validation prevents malicious uploads
- Secure file permissions on storage directories

## Performance Considerations

### Caching
- No explicit caching implemented
- Consider caching for frequently accessed data:
  - Available styles list
  - User permissions
  - API provider configurations

### Database Optimization
- Eager loading for relationships (styles → ai_models → api_providers)
- Consider indexes on frequently queried fields
- Automatic filesystem synchronization on image listing

### File Storage
- Images stored on local filesystem
- Consider CDN integration for global distribution
- Automatic cleanup of temporary files

## Future API Enhancements

### Potential Endpoints
- `GET /api/images/{id}/history` - Processing history for image
- `POST /api/images/batch-style-change` - Apply style to multiple images
- `GET /api/styles/search?q=term` - Search styles by name/description
- `POST /api/users/preferences` - Update user preferences
- `GET /api/admin/stats` - Application statistics for admins

### WebSocket Enhancements
- Real-time notifications for all users
- Live gallery updates when new images are processed
- Admin monitoring of processing queue status