API Constants & Enums
Relevant source files
The following files were used as context for generating this wiki page:
API Constants and Enums in the flext-api project provide a type-safe, centralized source of truth for protocol-specific values, HTTP methods, status codes, and validation limits. Built using Python 3.13+ features like StrEnum and PEP 695 type aliases, these constants integrate with Pydantic 2 for automatic validation in models and services.
This module ensures consistency across the platform by organizing constants into logical namespaces (e.g., Api, WebSocket, SSE, GraphQL) and utilizing a "DRY" (Don't Repeat Yourself) pattern where enumerations serve as both the definition and the validation source.
Sources: src/flext_api/history.json:constants.py:1-25, src/flext_api/history.json:constants.py:30-45
Core Architecture and Namespacing
The constants are encapsulated within the FlextApiConstants class (aliased as c), which extends core constants from flext_core and flext_web. The structure uses nested classes to separate different domain concerns within the API.
The diagram shows the hierarchical organization of API-related constants and sub-protocol namespaces.
Sources: src/flext_api/history.json:constants.py:30-40, src/flext_api/init.py:80-90
HTTP Protocol Constants
The Api.Method and Api.Status enums define the standard interactions for RESTful operations.
HTTP Methods and Validation Sets
The system supports standard HTTP methods and provides specialized sets for validation, such as "Safe" methods (which have no side effects) and "Active" methods.
| Constant Set | Values Included | Description |
|---|---|---|
Method | GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE | Standard HTTP verbs. |
ACTIVE_METHODS | GET, POST, PUT, DELETE | Methods primarily used for CRUD operations. |
SAFE_METHODS | GET, HEAD, OPTIONS, TRACE | Methods that do not modify state. |
VALID_HTTP_METHODS_LOWER | {get, post, ..., trace} | Lowercase set for case-insensitive validation. |
Sources: src/flext_api/history.json:constants.py:48-73, src/flext_api/history.json:constants.py:190-205
Operation Statuses
Operation statuses track the lifecycle of API requests and background tasks.
| Status | Category | Description |
|---|---|---|
IDLE, PENDING, RUNNING | Active | Operation is currently in progress. |
COMPLETED, SUCCESS | Success | Operation finished successfully. |
FAILED, ERROR | Failure | Operation ceased due to issues. |
TERMINAL_STATUSES | Set | {completed, failed, error} - signifies end of lifecycle. |
Sources: src/flext_api/history.json:constants.py:105-120, src/flext_api/history.json:constants.py:206-215
Protocol-Specific Namespaces
Beyond standard HTTP, the API defines constants for specialized communication protocols.
WebSockets (WS)
WebSocket constants manage the lifecycle and configuration of persistent connections.
- Default Ping Interval: 20.0 seconds.
- Max Message Size: 1 MiB (
2**20bytes). - Message Types:
TEXT,BINARY. - Status Codes:
101(Switching Protocols).
Sources: src/flext_api/history.json:constants.py:300-330
Server-Sent Events (SSE)
SSE constants define reconnection logic and timeouts for unidirectional streaming.
- Default Retry Timeout: 3000 ms.
- Default Read Timeout: 60.0 seconds.
- Protocols:
sse,server-sent-events,eventsource.
Sources: src/flext_api/history.json:constants.py:365-385
Webhooks
Webhook constants manage signature verification algorithms and delivery tracking.
- Algorithms:
SHA256,SHA512. - Delivery States:
DELIVERED,DELIVERED_AFTER_RETRY,FAILED.
Sources: src/flext_api/history.json:constants.py:122-145, src/flext_api/typings.py:40-45
Validation Limits and Network Defaults
The API enforces strict limits to ensure performance and security, mapped in VALIDATION_LIMITS.
| Constant | Value | Description |
|---|---|---|
MAX_URL_LENGTH | 2048 | Maximum length for API request URLs. |
DEFAULT_TIMEOUT | Derived from Web | Default request timeout in seconds. |
BACKOFF_FACTOR | 0.5 | Initial factor for exponential backoff retries. |
MIN_PORT / MAX_PORT | 1 / 65535 | Valid TCP port range. |
DEFAULT_BASE_URL | http://localhost:8000 | Default fallback for local API development. |
Sources: src/flext_api/history.json:constants.py:220-250, src/flext_api/history.json:constants.py:278-285
Type Integration (Typings)
Constants are tightly coupled with the FlextApiTypes (aliased as t). These types use constants to define strict Literal values and TypeAdapter instances for runtime validation.
class Api(FlextApiTypingsSerialization):
# Enforcing enum/string compatibility for webhooks
type WebhookDeliveryStatus = c.Api.WebhookDeliveryStatus | str
type WebhookAlgorithm = c.Api.WebhookAlgorithm | str
# Pre-configured Pydantic adapters using constant-driven logic
PORT_NUMBER_ADAPTER: u.TypeAdapter[t.PortNumber] = t.port_number_adapter()
HOSTNAME_ADAPTER: u.TypeAdapter[t.HostnameStr] = t.hostname_str_adapter()
Sources: src/flext_api/typings.py:35-45, src/flext_api/typings.py:55-60
Implementation Example: Request Normalization
The following flow illustrates how constants.py (c) and typings.py (t) are utilized during request construction.
This diagram shows how enums act as the single source of truth during payload building.
Sources: examples/01_basic_usage.py:26-45, src/flext_api/history.json:constants.py:50-60
Summary
The API Constants & Enums module provides the foundational data structures required for type-safe API communication. By leveraging StrEnum and centralized namespacing, the project ensures that protocols, status codes, and validation rules remain consistent across the client, server, and internal utility layers.