API Reference

This section provides information about the Active Annotate API configuration and how to access the interactive API documentation.

Application Configuration

class app.core.config.Settings(*args: Any, **kwargs: Any)[source]

Bases: BaseSettings

Application settings and configuration.

This class manages all configuration settings for the Active Annotate API. Settings are loaded from environment variables and have sensible defaults.

PROJECT_NAME

The name of the project/API.

Type:

str

VERSION

The current version of the API.

Type:

str

DESCRIPTION

A description of what the API does.

Type:

str

BACKEND_CORS_ORIGINS

List of allowed CORS origins. If None, CORS middleware is not added.

Type:

Optional[List[str]]

POSTGRES_SERVER

PostgreSQL server hostname.

Type:

str

POSTGRES_USER

PostgreSQL username.

Type:

str

POSTGRES_PASSWORD

PostgreSQL password.

Type:

str

POSTGRES_DB

PostgreSQL database name.

Type:

str

POSTGRES_PORT

PostgreSQL server port.

Type:

int

PROJECT_NAME: str = 'Active Annotate API'
VERSION: str = '0.1.0'
DESCRIPTION: str = 'Backend API for managing active learning annotation projects'
ACTIVE_ANNOTATE_HOSTNAME: str = 'http://api-dev.local:8000/'
BACKEND_CORS_ORIGINS: List[str] | None = None
DEBUG: bool | None = False
POSTGRES_SERVER: str = 'localhost'
POSTGRES_USER: str = 'postgres'
POSTGRES_PASSWORD: str = 'password'
POSTGRES_DB: str = 'active_annotate'
POSTGRES_PORT: int = 5432
property DATABASE_URL: str
property DATABASE_URL_SYNC: str

Main Application Setup

The FastAPI application is configured with the following features:

  • CORS middleware for cross-origin requests (when configured)

  • Automatic OpenAPI schema generation

  • Interactive documentation via Swagger UI and ReDoc

  • Type validation with Pydantic models

FastAPI application initialization
from app.core.config import settings
from app.db.database import init_db
from contextlib import asynccontextmanager
import logging


logging.basicConfig(
    level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

if settings.DEBUG:
    import debugpy
    debugpy.listen(("0.0.0.0", 5678))
    logging.info("Debbuger listens on port 5678")

Interactive API Documentation

FastAPI automatically generates comprehensive, interactive API documentation. Instead of maintaining separate documentation for endpoints, use the built-in OpenAPI documentation:

Swagger UI

The Swagger UI provides an interactive interface for exploring and testing API endpoints:

URL: http://localhost:8000/docs

Features: - Interactive endpoint testing - Request/response schemas - Parameter descriptions - Authentication testing - Example requests and responses

ReDoc

ReDoc provides a clean, readable API reference:

URL: http://localhost:8000/redoc

Features: - Clean, organized layout - Detailed request/response documentation - Schema visualization - Code examples in multiple languages

OpenAPI Schema

The raw OpenAPI schema is available at:

URL: http://localhost:8000/openapi.json

This JSON schema can be used to: - Generate client SDKs - Import into API testing tools - Integrate with other documentation systems - Validate API contracts

Getting Started with API Documentation

  1. Start the application:

    pipenv run uvicorn app.main:app --reload

  2. Open Swagger UI in your browser:

    Navigate to http://localhost:8000/docs

  3. Explore the endpoints:

    • Click on any endpoint to see details

    • Use “Try it out” to test endpoints

    • View request/response schemas

    • See example data

  4. For detailed reference:

    Visit http://localhost:8000/redoc for a comprehensive reference view

Why Use OpenAPI Documentation?

Advantages:

  • Always up-to-date - Generated directly from code

  • Interactive testing - Test endpoints without additional tools

  • Type-safe - Reflects actual Pydantic models and type hints

  • Standard format - Uses OpenAPI 3.0 specification

  • Zero maintenance - No manual documentation updates needed

  • Client generation - Can generate SDKs for various languages

Best Practices:

  • Add comprehensive docstrings to your endpoint functions

  • Use Pydantic models for request/response schemas

  • Include response examples in your endpoint definitions

  • Document error responses with appropriate status codes