HTTP Client Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The HTTP Client Protocol within the flext-oracle-wms project defines the communication layer between the library and the Oracle Warehouse Management System (WMS) Cloud REST API. It utilizes a railway-oriented programming (ROP) pattern for error handling, ensuring that all network operations return a structured result indicating success or failure rather than raising unhandled exceptions.
This protocol is implemented through a delegation model where the project's internal utilities wrap the flext-api infrastructure. It provides enterprise-grade features including connection pooling, automatic header normalization, and strict type validation for Oracle WMS entities.
Sources: src/flext_oracle_wms/_utilities/http_client.py:11-20, src/flext_oracle_wms/README.md:88-100
Architecture and Delegation
The architecture relies on a hierarchy of clients. The FlextOracleWmsUtilitiesClient acts as the primary interface, which in turn utilizes FlextApi to manage the underlying HTTP transport. This separation allows the library to apply Oracle-specific business logic (such as LGF API versioning) while leveraging a robust, general-purpose API engine for retries and connection management.
This diagram shows the flow from the high-level WMS Client through the HTTP utility layer to the external Oracle Cloud service.
Sources: src/flext_oracle_wms/_utilities/client.py:53-62, src/flext_oracle_wms/_utilities/http_client.py:22-30
HTTP Client Implementation
The HttpClient class provides a generic wrapper for REST operations. It includes built-in normalization for headers and request bodies, ensuring consistency across different types of WMS API calls.
Core Components
| Component | Description |
|---|---|
base_url | The root URL for the Oracle WMS instance, stripped of trailing slashes. |
timeout | Standard request timeout, defaulting to 30.0 seconds. |
verify_ssl | Boolean flag to enable/disable SSL certificate verification. |
_ensure_client() | Lazy-initialization method that configures the FlextApi instance. |
Sources: src/flext_oracle_wms/_utilities/http_client.py:25-45, src/flext_oracle_wms/_utilities/http_client.py:149-165
Request Execution Flow
The client follows a strict execution path for every request to maintain "continuous green" operational status and structured error reporting.
The sequence illustrates the railway-oriented flow where failures at any stage (validation, network, or parsing) are returned as a failed Result.
Sources: src/flext_oracle_wms/_utilities/http_client.py:167-200
WMS-Specific Operations
The FlextOracleWmsUtilitiesClient.Client implements high-level methods specific to Oracle WMS LGF (Logfire) API patterns. It manages entity discovery and data retrieval for core WMS objects.
Key Functional Methods
discover_entities(): Queries the/entitiesendpoint and decodes the response into a sequence of strings representing available WMS objects.get_entity_data(): Fetches records for a specific entity (e.g.,item,facility) with support for pagination (limit) and query filters.update_oblpn_tracking_number(): A specializedPUTrequest to update tracking information for Outbound License Plate Numbers.create_lpn(): APOSTrequest to create new License Plate Numbers in the system.
Sources: src/flext_oracle_wms/_utilities/client.py:126-140, src/flext_oracle_wms/_utilities/client.py:160-184, tests/unit/test_wms_client.py:175-195
Data Models and Validation
The protocol uses Pydantic models to validate API responses. If a response does not match the expected schema, the client returns a failure result rather than processing corrupt or unexpected data.
def _decode_response_model[T: m.BaseModel](https://github.com/flext-sh/flext-oracle-wms/blob/14186cd53084885fe37ad594b56ee1c2f28de482/payload%3A%20t.Api.ResponseBody%20%7C%20t.JsonValue%2C%0A%20%20%20%20model_type%3A%20type%5BT%5D%2C) -> p.Result[T]:
if isinstance(payload, dict):
return u.try_(
lambda: model_type.model_validate(payload),
catch=c.ValidationError,
).map_error(lambda exc: f"Invalid response payload: {exc}")
# ... handles str and bytes ...
Sources: src/flext_oracle_wms/_utilities/client.py:84-106
Error Handling and Status Codes
The protocol enforces a HTTP_BAD_REQUEST_THRESHOLD of 400. Any response with a status code equal to or greater than this threshold is automatically treated as a failure.
| Status Category | Logic | Result |
|---|---|---|
| 2xx | Successful request and valid body | Result.ok(data) |
| 4xx / 5xx | Client or Server error | Result.fail("HTTP {code}") |
| Network Error | Timeout or I/O failure | Result.fail("Request I/O error") |
| Parsing Error | Invalid JSON or Schema mismatch | Result.fail("Response parse error") |
Sources: src/flext_oracle_wms/_utilities/http_client.py:192-205, src/flext_oracle_wms/_utilities/client.py:228-234
Summary
The HTTP Client Protocol provides a robust foundation for interacting with Oracle WMS Cloud. By delegating low-level HTTP concerns to FlextApi and implementing a strict railway-oriented interface, the system ensures that entity discovery, data retrieval, and transactional updates are performed with high reliability and clear error traceability. This protocol is essential for maintaining the "enterprise-grade" quality standards required for warehouse integration.
Sources: src/flext_oracle_wms/README.md:12-25, tests/unit/test_declarative.py:130-150