Public API Facade
Relevant source files
The following files were used as context for generating this wiki page:
The Public API Facade in flext-web serves as the canonical, thin entry point for all runtime operations within the FLEXT Web interface. It is designed to consolidate complex service logic, health monitoring, and framework integration into a single, unified instance—conventionally accessed via from flext_web import web. This pattern ensures that operational code interacts with a stable interface while keeping internal service implementations, settings, and protocols modular and decoupled.
Architecturally, the facade is composed of multiple service classes through Method Resolution Order (MRO) inheritance, providing a flat surface for diverse operations such as application lifecycle management, authentication, and entity CRUD support. It strictly follows the "Public API Rule," which mandates that consumers (tests, examples, and operational code) exercise this facade rather than internal service classes.
Sources: development.md, src/README.md, development/README.md
Core Architecture and Entry Points
The facade is implemented as a thin layer in api.py that aggregates behavior from specialized service modules. It provides a shared web instance that acts as the primary operational surface.
Canonical Aliases and Namespaces
To maintain a Single Source of Truth (SSOT), the project exposes five structural namespaces alongside the operational facade:
| Namespace | Alias | Description |
|---|---|---|
FlextWebConstants | c.Web | Constants and Enums |
FlextWebTypes | t.Web | Public type contracts |
FlextWebProtocols | p.Web | Runtime protocols and registries |
FlextWebModels | m.Web | Public models and response projections |
FlextWebUtilities | u.Web | Public utilities |
Sources: src/README.md, api-reference/generated/overview.md
Service Composition Flow
The following diagram illustrates how the web facade aggregates functionality from various internal service layers:
The web instance is composed of all service classes, maintaining a thin api.py while behavior resides in specialized service implementations.
Sources: development.md, src/README.md
Runtime Surface and Lifecycle Operations
The facade exposes methods for managing the application lifecycle and framework-specific integrations. It allows developers to create and start web applications using different backends (FastAPI or Flask) through a single interface.
Key Lifecycle Methods
Common operations available directly on the web facade include:
- Framework Factories:
create_fastapi_app(),create_flask_app(), andcreate_app(). - Service Control:
start_service(host, port)andstop_service(). - Status Monitoring:
get_service_status().
Sources: development/README.md, development.md
Application Initialization Sequence
This sequence shows the typical flow of initializing and starting a service through the facade:
Operations prefer the web facade to maintain consistency across the platform.
Sources: development/README.md, development.md
Implementation Standards
The Public API Rule
Operational code, tests, and examples must prefer the web facade. Internal service classes (located in src/flext_web/services/) are not intended for direct import by consumers. This isolation ensures that internal refactoring does not break the public contract.
Settings and Configuration
Configuration access is namespaced and direct via the facade or the FlextWebSettings model. The base.py module provides a common service base that grants these services typed access to runtime web settings.
from flext_web import web
# Direct access to settings via facade
assert web.settings.debug is not None
# Starting a service via the facade entrypoint
status = web.start_service(host="127.0.0.1", port=8080)
if status.success:
print("Service started")
Sources: development.md, src/README.md, development/README.md
Summary
The Public API Facade is the central orchestration point for the flext-web package. By utilizing MRO composition and a strict aliasing strategy (c, t, p, m, u), it provides a consistent and typed developer experience. This architecture allows the underlying service implementations to evolve independently while maintaining a stable, unified operational surface for all FLEXT platform interactions.