FastAPI Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_web/services/app.py
• src/flext_web/services/api_runtime.py
• development.md
• guides/development.md
• pyproject.toml
• development/README.md

FastAPI integration within the flext-web project provides a modern, high-performance web interface for the FLEXT platform. It leverages FastAPI's asynchronous capabilities and Pydantic v2 for strict type safety and data validation. The integration is managed through specialized factory classes that ensure compliance with FLEXT's Clean Architecture principles and Railway-Oriented Programming (ROP) patterns.

The primary goal of this integration is to offer a type-safe operational surface for FLEXT services, allowing for automated documentation generation and standardized error handling. Developers interact with the FastAPI layer primarily through the web public facade, which abstracts the underlying framework complexities.

Sources: README.md, development.md:12-20, src/flext_web/services/app.py:16-24

Application Architecture

The FastAPI integration is structured around the FlextWebApp service coordinator. This class uses a nested FastAPIFactory to handle the instantiation and initial configuration of the fastapi.FastAPI object. The architecture strictly separates framework creation from runtime orchestration.

Core Components

• FlextWebApp: A service class inheriting from a base service (s) that coordinates web application lifecycle operations.
• FastAPIFactory: A specialized factory responsible for creating the FastAPI instance using validated configuration models.
• HealthHandler & InfoHandler: Specialized handlers that provide standardized JSON payloads for system health monitoring and metadata exposure.

The following diagram illustrates the relationship between the service coordinator and the FastAPI framework:

Application Creation Flow

The creation of a FastAPI application follows a functional pipeline, utilizing the Result pattern (p.Result) to handle success and failure states without throwing exceptions. This aligns with the project's Railway-Oriented Programming standard.

1. Configuration Validation: Configuration is passed via m.Web.FastAPIAppConfig or defaults are applied.
2. Instance Creation: FastAPIFactory.create_instance initializes the framework.
3. Endpoint Configuration: Standardized routes (/health, /info) are injected.
4. Middleware & Error Handling: Hooks are provided for extensible middleware and error handler registration.

Configuration and Metadata

FastAPI applications are configured using Pydantic models, specifically FastAPIAppConfig. This ensures that all parameters like API titles, versions, and documentation URLs are type-checked at runtime.

Parameter	Type	Default Source	Description
title	str	"FastAPI"	The title of the API displayed in docs.
version	str	final_config.version	The version string for the API.
description	str	c.Web.API_DEFAULT_DESCRIPTION	Detailed description of the service.
docs_url	str	c.Web.API_DOCS_URL	The path for Swagger UI.
redoc_url	str	c.Web.API_REDOC_URL	The path for ReDoc documentation.
openapi_url	str	c.Web.API_OPENAPI_URL	The path for the OpenAPI JSON schema.

Sources: src/flext_web/services/app.py:73-89, pyproject.toml:137-145

Standard Endpoints

The integration automatically registers two critical endpoints to ensure the application adheres to FLEXT platform standards:

Health Endpoint (/health)

Provides a heartbeat for the service. It returns a JSON object containing the status, service name, and an ISO timestamp.

• Method: GET
• Response Status: 200 OK (if healthy)
• Payload Example: {"status": "healthy", "service": "flext-web", "timestamp": "2025-01-01T00:00:00Z"}

Info Endpoint (/info)

Exposes application metadata and current runtime settings.

• Method: GET
• Payload Items: service, title, version, description, debug, timestamp.

Sources: src/flext_web/services/app.py:102-108, src/flext_web/services/app.py:173-205

Implementation Details

The implementation emphasizes "Zero Tolerance" for missing type safety. All FastAPI route handlers and factory methods must use complete type annotations.

# Implementation of the InfoHandler (src/flext_web/services/app.py:192-205)
class InfoHandler:
    @staticmethod
    def create_handler(
        settings: m.Web.FastAPIAppConfig,
    ) -> Callable[[], t.Web.FastApiEndpointPayload]:
        """Create FastAPI info handler function."""
        def info_handler() -> t.Web.FastApiEndpointPayload:
            return {
                "service": c.Web.SERVICE_NAME,
                "title": settings.title,
                "version": settings.version,
                "description": settings.description,
                "debug": settings.debug,
                "timestamp": u.generate_iso_timestamp(),
            }
        return info_handler

Sources: src/flext_web/services/app.py:192-205, guides/development.md:88-102

Conclusion

FastAPI integration in flext-web is characterized by its strict adherence to type safety and standardized service patterns. By encapsulating framework logic within FlextWebApp, the project ensures that web interfaces are robust, easily testable, and consistent across the FLEXT ecosystem. The use of ROP for application creation guarantees that configuration or runtime errors are handled gracefully and explicitly.