Core Protocols & Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Core Protocols & Interfaces" of the flext-oracle-oic extension define the structural contracts and interaction patterns required to communicate with Oracle Integration Cloud (OIC). This module centralizes runtime-checkable protocols, data models, and unified constants that ensure type safety and architectural consistency across the FLEXT ecosystem. It specifically addresses requirements for HTTP operations, authentication configurations, and integration entity representations.
Sources: src/flext_oracle_oic/protocols.py:1-13, src/flext_oracle_oic/constants.py:1-25
Service Protocols
The extension utilizes structural typing via Python's Protocol to define the capabilities of internal service components. The primary interface is the HTTPClient, which facilitates standardized interaction with OIC REST endpoints.
HTTPClient Interface
The HTTPClient protocol extends the base p.Service and defines synchronous methods for the four primary HTTP verbs. This ensures that any service implementation used by Oracle OIC services provides the necessary request methods returning a p.Result wrapper.
class HTTPClient(p.Service[t.JsonValue], Protocol):
def delete(self, url: str, *, headers: t.StrMapping | None = None) -> p.Result[bool]: ...
def get(self, url: str, *, headers: t.StrMapping | None = None) -> p.Result[t.JsonValue]: ...
def post(self, url: str, data: t.JsonMapping | None = None, *, headers: t.StrMapping | None = None) -> p.Result[t.JsonValue]: ...
def put(self, url: str, data: t.JsonMapping | None = None, *, headers: t.StrMapping | None = None) -> p.Result[t.JsonValue]: ...
Sources: src/flext_oracle_oic/protocols.py:19-49
Data Models and Contracts
The system relies on Pydantic models defined in FlextOracleOicModels to enforce data integrity for configurations and entities. These models act as the bridge between raw OIC API responses and the FLEXT application logic.
Configuration Models
| Model | Type | Description |
|---|---|---|
OICAuthConfig | m.Value | Stores IDCS OAuth2 client credentials, token URLs, and scopes. |
OICConnectionConfig | m.Value | Defines instance URL, API version (v1 default), timeouts, and retry logic. |
Entity Models
| Model | Type | Description |
|---|---|---|
OICIntegrationInfo | m.Entity | Captures integration metadata: integration_id, status, version, and description. |
OICConnectionInfo | m.Entity | Details connection status and adapter types (e.g., REST, SOAP, FTP). |
Sources: src/flext_oracle_oic/models.py:27-123
Logical Relationship Diagram
The following diagram illustrates how protocols, models, and clients interact within the architecture.
Interaction Flows
Authenticated Request Flow
The FlextOracleOicClient manages the complex handshake between OAuth2 token acquisition and API execution. It uses a "Railway-Oriented" pattern where each step returns a Result object.
CRUD Operation Patterns
Operations like creating or fetching integrations are orchestrated through mixins that leverage the core client and protocols. For example, FlextOracleOicIntegrationCrudMixin provides high-level methods that wrap raw client calls into domain-specific entities.
- Integration Creation: Validates
integration_databefore callingclient.create_integration. - Result Mapping: Uses
_build_integration_infoto map raw JSON payloads tom.OracleOic.OICIntegrationInfoentities.
Sources: src/flext_oracle_oic/services/integration_crud.py:22-60
Constants and Enums
The FlextOracleOicConstants (aliased as c) provides a single source of truth for literals used throughout the interfaces.
- Statuses:
ACTIVATED,DEACTIVATED,DRAFT,RUNNING,ERROR. - Connection Types:
REST,SOAP,DATABASE,FILE,FTP. - API Enpoints: Defaults to
/ic/api/integration/v1/healthfor monitoring.
Sources: src/flext_oracle_oic/constants.py:73-100, src/flext_oracle_oic/constants.py:155-159
Conclusion
The "Core Protocols & Interfaces" establish a robust, typed foundation for Oracle Integration Cloud interactions. By decoupling the HTTP client interface from its implementation and enforcing strict data models, the system ensures that high-level service mixins can operate on consistent, validated integration entities regardless of the underlying transport details.