192 lines
4.9 KiB
Markdown
192 lines
4.9 KiB
Markdown
# 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.
|