Aniworld/API_DOCUMENTATION.md

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

{
    "password": "your_master_password"
}

Response:

{
    "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:

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

Error Responses

Error responses include detailed error information:

{
  "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

# 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.