Core Data Models
Relevant source files
The following files were used as context for generating this wiki page:
The Core Data Models of the flext-api project provide a strictly typed foundation for building and interacting with high-performance REST APIs. These models leverage Pydantic 2 for runtime validation, Python 3.13+ type features (such as PEP 695 type aliases), and a railway-oriented result contract to ensure robustness across request normalization, response handling, and storage operations.
These models serve as the primary communication contract between the facade layer (e.g., FlextApi) and the underlying HTTP client and storage utilities. By centralizing type definitions and validation logic, the project ensures that data remains consistent from the point of entry (request construction) to the point of persistence (storage metadata).
API Communication Models
The communication layer defines how data is structured for transmission. It primarily focuses on normalizing HTTP requests and responses into typed objects that can be validated against defined schemas.
Request and Response Structure
The system uses m.Api.HttpRequest and m.Api.HttpResponse to encapsulate all data necessary for a network operation. Requests are constructed using utility facades that enforce validation rules for timeouts, headers, and payloads. Responses include metadata such as status codes and request IDs to facilitate tracking.
The diagram shows the relationship between the primary request and response models used in the API lifecycle.
Sources: examples/01_basic_usage.py:30-70, src/flext_api/typings.py:43-52
Communication Type Definitions
| Type Alias | Base Type | Description |
|---|---|---|
WebHeaders | t.ScalarOrStrSequenceMapping | Mapping of HTTP header keys to single or multiple values. |
WebParams | t.MappingKV[str, str | t.StrSequence] | Normalised URL query parameters. |
RequestBody | t.JsonMapping | str | t.StrictBytes | Acceptable types for HTTP request payloads. |
ResponseBody | t.JsonMapping | str | t.StrictBytes | None | Acceptable types for HTTP response payloads. |
Sources: src/flext_api/typings.py:43-47
Domain Constants and Enumerations
The project utilizes StrEnum for type-safe enumerations, which integrate directly with Pydantic validation to reject invalid values at the boundary.
HTTP Methods and Protocols
The FlextApiConstants.Api.Method enumeration defines standard HTTP verbs, while ProtocolMethod handles specialized routing for non-standard handlers like WebSockets (WS) or Server-Sent Events (SSE).
Validation flow for method normalization.
Sources: src/flext_api/constants.py:44-90
Operational Statuses
Operation lifecycles are tracked using the Status enumeration, categorized into terminal and success states.
| Enum Member | Value | Category |
|---|---|---|
IDLE | "idle" | Initial |
PENDING | "pending" | Transition |
RUNNING | "running" | Transition |
COMPLETED | "completed" | Terminal / Success |
FAILED | "failed" | Terminal / Error |
ERROR | "error" | Terminal / Error |
Sources: src/flext_api/constants.py:112-132, src/flext_api/constants.py:192-205
Storage and State Models
Storage models handle the persistence of API data, including metadata for caching and operational statistics.
Storage Components
- Storage.Settings: Configures the storage namespace and default Time-To-Live (TTL).
- Storage.Metadata: Wraps a
JsonValuewith a timestamp and TTL. - Storage.State: Tracks a collection of entries alongside hit/miss metrics.
- Storage.Stats: Provides a snapshot of storage health, including memory usage and operation counts.
Entity relationship diagram representing the hierarchy of storage models.
Sources: examples/01_basic_usage.py:126-150
Validation and Serialization Adapters
The system uses u.TypeAdapter for strict validation of primitives and complex structures within the Api namespace. This ensures that data entering the system adheres to the expected domain types before any logic is executed.
# Type adapters defined in the API namespace
CONTAINER_VALUE_ADAPTER: u.TypeAdapter[t.JsonValue] = u.TypeAdapter(t.JsonValue)
BINARY_CONTENT_ADAPTER: u.TypeAdapter[t.StrictBytes] = u.TypeAdapter(t.StrictBytes)
HOSTNAME_ADAPTER: u.TypeAdapter[t.HostnameStr] = u.TypeAdapter(t.HostnameStr)
PORT_NUMBER_ADAPTER: u.TypeAdapter[t.PortNumber] = u.TypeAdapter(t.PortNumber)
Sources: src/flext_api/typings.py:73-100
Summary
The Core Data Models in flext-api establish a unified domain language through the FlextApiTypes and FlextApiConstants classes. By integrating Pydantic-based validation with the Railway Result pattern (using p.Result), the architecture ensures that every data transformation—from a raw dictionary to a validated HttpRequest—is explicit, type-safe, and verifiable. This structure supports complex features such as Webhook signature verification and automated HTTP retries by providing reliable, immutable data structures across the library.