Quickstart & Basic Usage
Relevant source files
The following files were used as context for generating this wiki page:
The FLEXT API is a high-performance REST API framework built with FastAPI, designed to provide typed request normalization, Pydantic 2 model validation, and structured response ergonomics. The "Quickstart & Basic Usage" guide demonstrates how to interact with the public surface of the library, specifically using the FlextApi facade and its associated utilities to build, validate, and process HTTP interactions within a railway-oriented programming model.
The basic usage flow centers on the FlextApi class and a set of public aliases (c, m, p, r, s, t, u) that represent constants, models, protocols, results, service bases, types, and utilities respectively. This structure ensures that developers can perform complex API operations—such as request payload construction and storage state management—without depending on external HTTP services during development or testing.
Sources: README.md:8-10, examples/README.md:3-6, examples/01_basic_usage.py:12-15
Core Initialization and Setup
To begin using the library, developers typically inherit from the typed service base s or instantiate the FlextApi facade directly. The FlextApi class manages runtime settings, such as base_url, timeout, and max_retries, which are configured through the infrastructure's settings management.
Architecture Overview
The library follows a Clean Architecture approach, separating the domain layer (entities and value objects) from the infrastructure layer (FastAPI factory and HTTP client).
The diagram above illustrates the relationship between the public facade and the internal core services and data layers.
Sources: src/README.md:12-35, examples/README.md:27-35, examples/01_basic_usage.py:84-95
Request Normalization and Validation
A key feature of FLEXT API is the normalization of request payloads before they are parsed into Pydantic models. This is achieved through u.Api.RequestUtils, which provides methods for coercing timeouts and building valid request payloads with specific HTTP methods, headers, and parameters.
Request Building Flow
- Coerce Timeout: Ensure the timeout is a positive numeric value.
- Build Payload: Construct a raw JSON-mapping of the request details.
- Parse Model: Validate the payload against the
m.Api.HttpRequestPydantic model.
The sequence diagram shows the steps to generate a validated HTTP request object.
Sources: examples/01_basic_usage.py:23-51, examples/README.md:43-47
Valid HTTP Methods
The framework uses a StrEnum for type-safe HTTP method definitions, ensuring automatic Pydantic validation.
| Method | Description |
|---|---|
GET | Retrieve resource |
POST | Create resource |
PUT | Update resource |
DELETE | Remove resource |
PATCH | Partial update |
WS | WebSocket protocol pseudo-method |
SSE | Server-Sent Events pseudo-method |
Sources: src/flext_api/history.json (constants.py):45-78
Result Handling (Railway Contract)
FLEXT API utilizes a "railway" result contract via p.Result and the r alias. This pattern avoids standard exception-based control flow in favor of explicit success and failure states.
| Attribute | Type | Description |
|---|---|---|
success | bool | True if the operation succeeded |
failure | bool | True if the operation failed |
value | T | The resulting data (if success) |
error | str | None | The error message (if failure) |
Sources: examples/01_basic_usage.py:97-120, examples/README.md:48-49
Storage and Statistics
The library includes built-in models for managing storage state and monitoring API statistics without additional helper layers. This includes tracking cache hits, misses, and memory usage.
Data Model: Storage Stats
| Field | Type | Description |
|---|---|---|
total_operations | int | Total count of storage operations |
cache_hits | int | Count of successful cache retrievals |
cache_misses | int | Count of failed cache retrievals |
storage_size | int | Number of entries in storage |
namespace | str | Logical grouping for the storage |
Sources: examples/01_basic_usage.py:126-150, src/README.md:31-33
Execution Summary
To run the basic usage example provided in the codebase, use the following command from the project root:
PYTHONPATH=src python -m examples.01_basic_usage
Sources: examples/README.md:15-17
The basic usage demonstrates that the FlextApi facade successfully integrates settings management, request construction through u.Api.RequestUtils, Pydantic 2 validation via m.Api, and structured storage metadata handling, all wrapped in a consistent p.Result contract.