Protocols & Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The flext-tap-oracle-oic project utilizes a series of structural protocols and interfaces to ensure compatibility with the Singer specification and the FLEXT ecosystem. These interfaces define the contracts for pagination, data transformation, and stream modeling, allowing the tap to interact seamlessly with Oracle Integration Cloud (OIC) APIs while maintaining strict typing and architectural consistency.
The core of the interface design follows the "Dependency Inversion Principle" (DIP), where high-level business logic depends on abstractions rather than concrete implementations. This is primarily achieved through Python Protocol classes that define structural subtyping for components like paginators and property lists.
Sources: src/flext_tap_oracle_oic/protocols.py:12-23, AGENTS.md:144-148
Structural Protocols
The project defines specific structural protocols that components must adhere to. These are located in the protocols.py module and provide the interface for stream-level operations.
Paginator Protocol
The Paginator protocol defines the contract for handling OIC API pagination. It ensures that any paginator implementation can provide the next offset or token based on an HTTP response.
The Paginator is used by stream models to calculate the offset for subsequent API requests.
Sources: src/flext_tap_oracle_oic/protocols.py:27-38, src/flext_tap_oracle_oic/models.py:144-150
PropertiesListLike Protocol
This protocol provides a structural contract for objects compatible with Singer PropertiesList. It requires a to_dict() method that returns a JSON-compatible mapping of the stream schema.
Sources: src/flext_tap_oracle_oic/protocols.py:40-45, src/flext_tap_oracle_oic/_models/streams.py:20-23
Abstract Interfaces & Base Classes
The project utilizes base classes that act as interfaces for specific OIC API interactions.
OICBaseStream Interface
The OICBaseStream class serves as the primary interface for all OIC streams. It defines required metadata and methods for URL construction, parameter building, and response parsing.
| Property/Method | Type | Description |
|---|---|---|
name | str | The unique name of the stream (e.g., "integrations"). |
api_path | str | The specific endpoint path for the resource. |
api_category | str | Category (core, monitoring, b2b, etc.) to determine base path. |
primary_keys | StrSequence | List of fields that uniquely identify a record. |
get_url_params() | Method | Interface for building query parameters like limit and offset. |
parse_response() | Method | Interface for transforming HTTP responses into record iterators. |
Sources: src/flext_tap_oracle_oic/models.py:80-142, src/flext_tap_oracle_oic/_models/streams.py:29-40
Authentication & Client Interfaces
The tap interacts with OIC using an authenticated client that follows a standard request/response interface.
Authenticator Interface
The FlextOracleOicAuthenticator provides a single method for obtaining tokens:
get_access_token(): Returns aResult[str]containing the OAuth2 bearer token.
API Client Interface
The FlextTapOracleOicClient encapsulates the logic for making authenticated requests.
Configuration Interfaces
The tap configuration is managed through a typed interface using Pydantic, ensuring that all required connection parameters are present.
| Field | Description | Source |
|---|---|---|
oauth_client_id | Unique ID for the OAuth2 client. | tap.py:127 |
oauth_client_secret | Secret for the OAuth2 client. | tap.py:128 |
oauth_token_url | URL to request OAuth2 tokens. | tap.py:133 |
oic_url | Base URL for the OIC instance. | tap.py:134 |
Sources: src/flext_tap_oracle_oic/tap.py:125-144
Conclusion
The protocols and interfaces in flext-tap-oracle-oic establish a rigid contract between the tap's core logic and the Oracle Integration Cloud API. By utilizing structural protocols for pagination and property management, and standardized base classes for stream implementation, the project ensures high maintainability and consistent behavior across different OIC resource types.