# AniWorld FastAPI Documentation

## Overview

AniWorld has been successfully migrated from Flask to FastAPI, providing improved performance, automatic API documentation, and modern async support.

## Accessing API Documentation

### Interactive API Documentation

FastAPI automatically generates interactive API documentation that you can access at:

-   **Swagger UI**: `http://localhost:8000/docs`
-   **ReDoc**: `http://localhost:8000/redoc`

These interfaces allow you to:

-   Browse all available endpoints
-   View request/response schemas
-   Test API endpoints directly from the browser
-   Download OpenAPI schema

### OpenAPI Schema

The complete OpenAPI 3.0 schema is available at:

-   **JSON Format**: `http://localhost:8000/openapi.json`

## Authentication

### Master Password Authentication

AniWorld uses a simple master password authentication system with JWT tokens.

#### Login Process

1. **POST** `/auth/login`
    - Send master password in request body
    - Receive JWT token in response
    - Token expires in 24 hours

```json
{
    "password": "your_master_password"
}
```

Response:

```json
{
    "success": true,
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "message": "Login successful"
}
```

#### Using Authentication Token

Include the token in the `Authorization` header for authenticated requests:

```
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
```

## API Endpoints

### System Health

-   **GET** `/health` - Check system health and status
-   **GET** `/api/system/database/health` - Check database connectivity
-   **GET** `/api/system/config` - Get system configuration

### Authentication

-   **POST** `/auth/login` - Authenticate and get JWT token
-   **GET** `/auth/verify` - Verify current token validity
-   **POST** `/auth/logout` - Logout and invalidate token
-   **GET** `/api/auth/status` - Get current authentication status

### Anime Management

-   **GET** `/api/anime/search` - Search for anime series
-   **GET** `/api/anime/{anime_id}` - Get specific anime details
-   **GET** `/api/anime/{anime_id}/episodes` - Get episodes for an anime

### Episode Management

-   **GET** `/api/episodes/{episode_id}` - Get specific episode details

### Series Management

-   **POST** `/api/add_series` - Add a new series to tracking
-   **POST** `/api/download` - Start episode download

### Web Interface

-   **GET** `/` - Main application interface
-   **GET** `/app` - Application dashboard
-   **GET** `/login` - Login page
-   **GET** `/setup` - Setup page
-   **GET** `/queue` - Download queue interface

## Response Formats

### Success Responses

All successful API responses follow this structure:

```json
{
  "success": true,
  "data": {...},
  "message": "Operation completed successfully"
}
```

### Error Responses

Error responses include detailed error information:

```json
{
  "success": false,
  "error": "Error description",
  "code": "ERROR_CODE",
  "details": {...}
}
```

## Status Codes

-   **200 OK** - Successful operation
-   **201 Created** - Resource created successfully
-   **400 Bad Request** - Invalid request data
-   **401 Unauthorized** - Authentication required
-   **403 Forbidden** - Insufficient permissions
-   **404 Not Found** - Resource not found
-   **422 Unprocessable Entity** - Validation error
-   **500 Internal Server Error** - Server error

## Rate Limiting

Currently, no rate limiting is implemented, but it may be added in future versions.

## WebSocket Support

Real-time updates are available through WebSocket connections for:

-   Download progress updates
-   Scan progress updates
-   System status changes

## Migration Notes

### Changes from Flask

1. **Automatic Documentation**: FastAPI provides built-in OpenAPI documentation
2. **Type Safety**: Full request/response validation with Pydantic
3. **Async Support**: Native async/await support for better performance
4. **Modern Standards**: OpenAPI 3.0, JSON Schema validation
5. **Better Error Handling**: Structured error responses with detailed information

### Breaking Changes

-   Authentication tokens are now JWT-based instead of session-based
-   Request/response formats may have slight differences
-   Some endpoint URLs may have changed
-   WebSocket endpoints use FastAPI WebSocket pattern

## Development

### Running the Server

```bash
# Development mode with auto-reload
uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload

# Production mode
uvicorn src.server.fastapi_app:app --host 0.0.0.0 --port 8000
```

### Environment Variables

-   `MASTER_PASSWORD_HASH` - Hashed master password
-   `JWT_SECRET_KEY` - Secret key for JWT token signing
-   `LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR)

## Support

For issues, questions, or contributions, please visit the project repository or contact the development team.