Home

Relevant source files

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

• README.md
• src/README.md
• pyproject.toml
• examples/README.md
• examples/01_basic_usage.py
• src/flext_api/history.json
• src/flext_api/init.py
• AGENTS.md

The flext-api project is a high-performance REST API library built on top of FastAPI, designed for enterprise-grade applications requiring strict typing and robust architecture. It serves as a platform component within the FLEXT ecosystem, emphasizing request normalization, Pydantic 2 model validation, and a "railway" result contract for explicit success and failure handling.

Sources: README.md:8-10, examples/README.md:3-5, pyproject.toml:21-31

Architecture Overview

The library follows a layered architecture, separating concerns between domain logic, infrastructure, and public API facades. It leverages Python 3.13+ features such as StrEnum for type-safe enumerations and PEP 695 type aliases.

Directory Structure and Layers

Layer	Responsibility	Key Files
Public API	Lazy-loaded exports and facade classes for consumer use.	src/flext_api/__init__.py, src/flext_api/api.py
Core Services	Main logic for HTTP client operations and app factory.	src/flext_api/client.py, src/flext_api/app.py
Data & Logic	Query/Response builders and Pydantic field definitions.	src/flext_api/builder.py, src/flext_api/fields.py
Infrastructure	External concerns, configuration management, and storage.	src/flext_api/infrastructure/, src/flext_api/settings.py
Domain	Core entities and value objects.	src/flext_api/domain/entities.py

Sources: src/README.md:16-52, src/flext_api/history.json:1-20

Component Relationship Diagram

This diagram illustrates how the core components of flext-api interact to process requests and manage state.

Core Technical Patterns

1. Unified Type System

The project uses a consolidated namespace for types (FlextApiTypes), avoiding weak types and ensuring strict typing across the library. This includes specialized adapters for JSON validation and binary content.

class Api(FlextApiTypingsSerialization):
    type WebHeaders = t.ScalarOrStrSequenceMapping
    type WebParams = t.MappingKV[str, str | t.StrSequence]
    API_JSON_VALUE_ADAPTER: u.TypeAdapter[t.JsonValue] = u.TypeAdapter(t.JsonValue)

Sources: src/flext_api/history.json: typings.py contents

2. Request Normalization and Validation

Requests are normalized through u.Api.RequestUtils before being parsed into Pydantic 2 models. This ensures that inputs like timeouts or headers are consistent before reaching the execution phase.

3. Railway Result Contract

The library utilizes a Result pattern (p.Result) to handle success and failure explicitly without relying on exception-based control flow for expected logic branches.

• Success: Handled via .ok() and checked with .success.
• Failure: Handled via .fail() and checked with .failure, providing an explicit .error message.

Sources: examples/01_basic_usage.py:84-110, examples/README.md:14-25

Component Specifications

Constants and Enumerations

Constants are organized into logical namespaces (e.g., Api, WebSocket, SSE) using StrEnum for automatic Pydantic validation.

Namespace	Key Constants	Description
Api.Method	GET, POST, PUT, DELETE	Standard HTTP methods.
Api.Status	PENDING, RUNNING, SUCCESS, FAILED	Operation lifecycle statuses.
Api.ContentType	application/json, application/xml	Supported MIME types.
HTTP.Protocol	http/1.1, http/2, http/3	Supported transmission protocols.

Sources: src/flext_api/history.json: constants.py contents

Execution Flow

The FlextApi facade manages the execution of API operations by composing the HTTP client and configuration settings.

Development and Quality Gates

The project enforces strict quality standards via "Universal Agent Law" and "Quality Gates" defined in AGENTS.md.

• Zero-Tolerance: Root cause fixes only, no dead code, and no stubs or fakes.
• Testing: Organized into unit/ (fast isolated tests), integration/ (external services), and e2e/ (workflow validation).
• Make Contract: Canonical verbs include check, test, val, and docs.

Sources: AGENTS.md:10-50, tests/README.md:16-45, README.md:40-45