OIC Target API Gateway
Relevant source files
The following files were used as context for generating this wiki page:
The OIC Target API Gateway serves as the centralized orchestration layer for the flext-target-oracle-oic Singer target. Its primary purpose is to manage the lifecycle of data ingestion into Oracle Integration Cloud (OIC) by coordinating stream-specific sinks, handling secure OAuth2 authentication, and enforcing data model integrity through validated Pydantic schemas.
As part of the FLEXT integration framework, the gateway abstracts the complexities of the OIC REST API, providing a uniform interface for processing records across various OIC entities such as connections, integrations, and packages. It relies on the FlextMeltanoTargetServiceBase to leverage standardized Singer target behaviors while implementing domain-specific logic for OIC-specific endpoints.
Sources: src/flext_target_oracle_oic/api.py:1-25, src/flext_target_oracle_oic/target.py:74-85
Architectural Overview
The architecture follows a hierarchical pattern where a main entry point orchestrates multiple specialized "Sinks." Each sink is responsible for a specific data stream defined by OIC's API structure.
Component Relationship
The gateway is composed of several key classes that manage configuration, authentication, and execution:
- FlextTargetOracleOicService: The top-level orchestrator that interfaces with the FLEXT service runtime.
- FlextTargetOracleOic: The Singer target class that manages the mapping between stream names and their corresponding sink implementations.
- Authenticator: A utility class dedicated to managing OAuth2 client credentials flows and header generation.
- Sinks: specialized classes (e.g.,
FlextTargetOracleOicConnectionsSink) that handle the actual processing of records for specific streams.
The diagram above illustrates the delegation flow from the initial service call down to individual stream sinks.
Sources: src/flext_target_oracle_oic/api.py:27-44, src/flext_target_oracle_oic/target.py:74-92, src/flext_target_oracle_oic/utilities.py:53-62
Authentication and Security
The gateway implements a strict OAuth2 Client Credentials flow to interact with the Oracle Identity Cloud Service (IDCS) or OIC's built-in identity provider.
OAuth2 Implementation
Authentication logic is encapsulated in the Authenticator class. It manages token acquisition, caching (session-based), and automatic header construction for downstream API requests.
| Component | Description | Source |
|---|---|---|
| Grant Type | client_credentials | utilities.py:72 |
| Token URL | Configurable endpoint for OAuth2 token exchange | settings.py:32 |
| Auth Scheme | Defaults to Bearer | utilities.py:61 |
| Scope | Optional; defaults to oic_instance | settings.py:38 |
This sequence ensures that every request to the OIC API is preceded by a valid authorization check.
Sources: src/flext_target_oracle_oic/utilities.py:64-106, src/flext_target_oracle_oic/constants.py:33
Data Stream Definitions
The gateway supports four primary streams, each mapped to specific OIC API functional areas. These are managed via the FlextTargetOracleOic target class using constants for stream identification.
| Stream Name | Sink Class | OIC Purpose |
|---|---|---|
connections | FlextTargetOracleOicConnectionsSink | Managing adapter connections and properties |
integrations | FlextTargetOracleOicIntegrationsSink | Deploying and managing integration flows |
packages | FlextTargetOracleOicPackagesSink | Grouping integrations into exportable packages |
lookups | FlextTargetOracleOicLookupsSink | Managing key-value mapping tables |
Sources: src/flext_target_oracle_oic/target.py:86-92, src/flext_target_oracle_oic/constants.py:16-19
Configuration and Runtime Settings
The gateway requires a specific set of environment variables or configuration keys to operate. These are validated using Pydantic via the FlextTargetOracleOicSettings class.
Required Configuration Fields
All fields are prefixed with FLEXT_TARGET_ORACLE_OIC_ when provided via environment variables.
base_url: The root URL for the OIC instance (e.g.,https://instance.integration.ocp.oraclecloud.com).oauth_client_id: The client identifier from IDCS.oauth_client_secret: The client secret (handled as aSecretStr).oauth_token_url: The full URL to the OAuth2 token endpoint.timeout: HTTP request timeout in seconds (default: 300s).
Sources: src/flext_target_oracle_oic/settings.py:19-54, src/flext_target_oracle_oic/utilities.py:30-38
Domain Models and Validation
The gateway uses a structured domain model to ensure that data being pushed to OIC adheres to the expected schema. Models are defined within the FlextTargetOracleOicModels namespace.
Core Data Structures
class OICConnection(m.ArbitraryTypesModel):
id: Annotated[t.NonEmptyStr, u.Field(description="Unique connection identifier")]
name: Annotated[t.NonEmptyStr, u.Field(description="Connection name")]
adapter_type: Annotated[t.NonEmptyStr, u.Field(description="Type of adapter used")]
properties: Annotated[t.JsonMapping, u.Field(description="Connection properties")]
The gateway provides factory methods in utilities.py to transform raw Singer records into these validated Pydantic models before processing.
Sources: src/flext_target_oracle_oic/models.py:17-31, src/flext_target_oracle_oic/utilities.py:41-52
Summary
The OIC Target API Gateway provides a robust, typed interface for synchronizing data with Oracle Integration Cloud. By utilizing a sink-based architecture and a dedicated OAuth2 authenticator, it ensures that data flows are secure, modular, and compliant with OIC's API requirements. The system's reliance on Pydantic models for validation guarantees that incoming Singer records are correctly formatted before they reach the OIC integration endpoints.