Internal API Abstraction Reference

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_oracle_oic/api.py
• src/flext_oracle_oic/ext_client.py
• src/flext_oracle_oic/services/integration_crud.py
• src/flext_oracle_oic/models.py
• src/flext_oracle_oic/constants.py
• src/flext_oracle_oic/settings.py

The Internal API Abstraction Reference provides a comprehensive overview of how the flext-oracle-oic project encapsulates and manages interactions with the Oracle Integration Cloud (OIC) REST APIs. It defines a multi-layered architecture—from low-level HTTP requests and OAuth2 token management to high-level domain services and thin facades—to ensure consistent, railway-oriented error handling and enterprise-grade observability.

This abstraction layer is built upon the FLEXT Unified Module Pattern, consolidating client logic, service mixins, and typed data models into a single cohesive interface for managing integrations, connections, and orchestration patterns.
Sources: src/flext_oracle_oic/api.py:1-35, src/flext_oracle_oic/ext_client.py:1-25

Architectural Overview

The project follows a layered abstraction strategy to decouple business logic from OIC-specific API quirks.

Layered Abstraction Model

1. Facade Layer (FlextOracleOicApi): A thin entry point that integrates with the broader FLEXT ecosystem (Bus, Container, Context) and delegates domain logic to the Service Layer.
2. Service Layer (FlextOracleOicService): Orchestrates complex operations by combining various mixins (CRUD, Lifecycle, Monitoring).
3. Client Layer (FlextOracleOicClient): Manages low-level API concerns such as OAuth2 authentication, pagination, and raw HTTP requests using flext-api.
4. Model Layer (FlextOracleOicModels): Defines strictly typed Pydantic entities for configuration and API responses.

The following diagram illustrates the relationship between these layers:

This diagram shows the flow of requests from the user through the thin facade down to the internal client.
Sources: src/flext_oracle_oic/api.py:32-60, src/flext_oracle_oic/services/integration_crud.py:20-25, src/flext_oracle_oic/ext_client.py:28-50

Low-Level Client Abstraction (FlextOracleOicClient)

The FlextOracleOicClient serves as the primary engine for raw OIC interactions. It handles the complexity of OAuth2 client credentials flows and provides generic methods for authenticated requests.

Key Authentication Flow

The client implements a railway-oriented approach to obtaining access tokens. It validates the configuration, prepares the OAuth request, executes it, and parses the response.

This sequence diagram visualizes the OAuth2 client credentials acquisition process.
Sources: src/flext_oracle_oic/ext_client.py:116-126, src/flext_oracle_oic/ext_client.py:317-345

Paginated Requests

The client abstracts the OIC pagination logic (using offset and limit parameters) to return consolidated lists of records.

Feature	Method	Description
Pagination	paginate_request	Automatically follows hasMore flags in responses until all items are collected.
Dynamic Filtering	get_integrations	Uses OIC's q parameter syntax for filtering by status or type.
Request Normalization	_to_api_payload	Converts complex Python objects into API-compliant JSON structures.

Sources: src/flext_oracle_oic/ext_client.py:207-240, src/flext_oracle_oic/ext_client.py:353-366

Service Mixin Logic

High-level operations are distributed across mixins, such as FlextOracleOicIntegrationCrudMixin, which transform raw JSON responses into typed domain entities.

Integration CRUD Operations

The service layer uses the client to perform operations and then maps the results to m.OracleOic.OICIntegrationInfo entities.

# Implementation snippet from FlextOracleOicIntegrationCrudMixin
def fetch_integration(self, integration_id: str) -> p.Result[m.OracleOic.OICIntegrationInfo]:
    client = self._get_client().value
    integrations = client.get_integrations().value
    integration_data = next((item for item in integrations if item.get("id") == integration_id), None)
    return r[m.OracleOic.OICIntegrationInfo].ok(self._build_integration_info(integration_data))

Sources: src/flext_oracle_oic/services/integration_crud.py:61-96

Configuration and Models

The abstraction relies on a hierarchy of models defined in FlextOracleOicModels.

Connection Configuration

The OICConnectionConfig model ensures that all necessary parameters for the OIC instance are present and valid.

Field	Type	Default	Description
base_url	str	N/A	OIC instance base URL
api_version	str	"v1"	OIC API version
request_timeout	int	30	Timeout in seconds
verify_ssl	bool	True	SSL certificate verification

Sources: src/flext_oracle_oic/models.py:59-86, src/flext_oracle_oic/settings.py:35-45

Data Entity Model: OICIntegrationInfo

This model represents a single integration flow within OIC.

Field	Description
integration_id	Unique identifier (ID)
name	Human-readable name
status	Current state (e.g., ACTIVATED, DRAFT)
integration_version	Version string (format XX.XX.XXXX)

Sources: src/flext_oracle_oic/models.py:88-109

Constant Definitions

The FlextOracleOicConstants class provides a centralized source of truth for statuses, API endpoints, and validation rules.

This class diagram highlights the organization of constant namespaces.
Sources: src/flext_oracle_oic/constants.py:48-150

Conclusion

The Internal API Abstraction Reference demonstrates a robust architecture for managing complex enterprise integrations. By separating the low-level HTTP/OAuth2 handling from the domain-specific business logic and providing a thin, ecosystem-integrated facade, the project ensures that Oracle Integration Cloud operations are reliable, type-safe, and easily maintainable. This structure allows developers to interact with OIC integrations and orchestration patterns without needing to manage the underlying REST communication details.