API Discovery Mechanisms
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The API Discovery Mechanisms in the flext-oracle-wms library provide automated capabilities for exploring and introspecting the Oracle Warehouse Management System (WMS) Cloud environment. This system is designed to programmatically identify available REST API endpoints, discover warehouse entities (such as inventory, orders, and facilities), and introspect data schemas without manual configuration.
The primary scope of discovery includes entity identification, metadata extraction for field mapping, and the generation of Singer-compatible schemas for downstream data integration pipelines. These mechanisms support different operational modes, ranging from a "Complete Discovery" using administrator credentials to "Optimized" and "Focused" modes for high-priority data points.
Sources: src/flext_oracle_wms/README.md:37-38, tests/unit/oracle_wms_complete_discovery.py:1-13
Core Discovery Architecture
The discovery system is built upon the FlextOracleWmsUtilitiesClient, which interacts with the Oracle WMS Cloud LGF API (v10). It employs a layered approach to transition from high-level API cataloging to specific record-level schema introspection.
Discovery Workflow
The following diagram illustrates the sequence of operations performed during a comprehensive discovery session:
The discovery process begins with client initialization and moves through cataloging and sampling before producing final schema artifacts.
Sources: tests/unit/oracle_wms_complete_discovery.py:48-61, tests/unit/oracle_wms_optimized_discovery.py:59-99
Discovery Mechanisms & Modes
The library implements three distinct strategies for API and entity discovery:
1. Complete Administrator Discovery
This mode utilizes administrator-level credentials to perform a full exploration of all 22+ Oracle WMS APIs. It systematically tests different categories such as DATA_EXTRACT, ENTITY_OPERATIONS, and SETUP_TRANSACTIONAL to ensure full coverage.
Sources: tests/unit/oracle_wms_complete_discovery.py:15-32, tests/unit/oracle_wms_complete_discovery.py:63-87
2. Optimized Priority Discovery
Focuses on a pre-defined set of high-priority warehouse entities (e.g., company, facility, item, inventory, order_hdr). It processes requests in parallel batches to reduce latency and maximize throughput during the discovery phase.
Sources: tests/unit/oracle_wms_optimized_discovery.py:32-57, tests/unit/oracle_wms_optimized_discovery.py:101-125
3. Focused Data Scanning
A performance-oriented mode that quickly scans for entities that contain actual data records. It skips empty entities to focus schema generation efforts only on active warehouse data points.
Sources: tests/unit/oracle_wms_focused_discovery.py:65-95
Entity Metadata and Schema Generation
Discovery extends beyond simple endpoint listing to deep inspection of data structures. The system samples records to determine field names and data types.
Type Mapping Logic
The mechanism maps Oracle/Python data types to Singer-compatible types based on value analysis:
| Oracle/Python Type | Singer Type | Detection Logic |
|---|---|---|
bool | boolean | Instance check of sample value |
int | integer | Instance check; checks if field ends in _id |
str (Timestamp) | string (date-time) | Checks for indicators like _ts, _at, or ISO8601 patterns |
str (Date) | string (date) | Checks for _date indicators and absence of time components |
dict | object | JSON structure introspection |
Sources: tests/unit/oracle_wms_optimized_discovery.py:227-268, tests/unit/oracle_wms_focused_discovery.py:228-255
Key Property Identification
The discovery engine automatically identifies primary keys by looking for specific patterns (e.g., id, code, nbr) associated with specific Oracle WMS entities.
Automatic detection of key properties ensures that generated Singer catalogs correctly identify unique records.
Sources: tests/unit/oracle_wms_optimized_discovery.py:279-304, tests/unit/oracle_wms_focused_discovery.py:277-298
Key Implementation Components
| Component | Responsibility | Relevant Class/Method |
|---|---|---|
| API Discovery | Lists available REST API endpoints | client.discover_entities() |
| Metadata Processor | Extracts field types and samples from real data | _analyze_single_entity() |
| Schema Generator | Creates JSON Schema/Singer artifacts | generate_complete_singer_schemas() |
| API Catalog | Declarative list of known WMS API versions | FlextOracleWmsApi.FLEXT_ORACLE_WMS_APIS |
Sources: src/flext_oracle_wms/_utilities/client.py:126-135, tests/unit/oracle_wms_optimized_discovery.py:127-160, examples/03_complete_functionality_showcase.py:108-115
Code Snippet: Entity Discovery
# From src/flext_oracle_wms/_utilities/client.py:126-135
def discover_entities(self) -> p.Result[t.StrSequence]:
"""Discover available Oracle WMS entities."""
result = self.get("/entities")
if result.failure:
return r[t.StrSequence].fail(result.error)
payload_result = self._decode_response_model(
result.value.body,
m.OracleWms.EntitiesResponse,
)
# ... handles validation and returns entity list
Sources: src/flext_oracle_wms/_utilities/client.py:126-135
Conclusion
API Discovery Mechanisms within flext-oracle-wms serve as the foundation for dynamic data integration. By combining automated endpoint discovery with deep record introspection and Singer-compatible schema generation, the system minimizes the configuration overhead required to synchronize data with Oracle WMS Cloud. The multi-modal approach (Complete, Optimized, Focused) allows developers to balance discovery depth with execution performance depending on the integration context.