API Reference & Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The FLEXT-LDIF API serves as the Application Layer for the enterprise LDIF processing library, orchestrating business operations through a clean, unified facade. It provides high-level abstractions for parsing, validating, transforming, and migrating LDIF data across various LDAP server types, including OID, OUD, OpenLDAP, and Active Directory.
The API is designed following Clean Architecture principles, where the api.py module acts as the primary entry point for the FLEXT ecosystem. It integrates domain models, infrastructure services, and cross-cutting utilities into a single, cohesive interface that supports both synchronous workflows and railway-oriented error handling via the Result pattern.
Sources: src/README.md:12-25, src/flext_ldif/api.py, examples/README.md:131-150
Core API Architecture
The architecture centers on the FlextLdif class (exposed via the ldif alias), which manages dependencies and provides access to specialized services. It utilizes a singleton-capable pattern where multiple instances can operate independently, each with its own configuration and context.
Component Interaction
The following diagram illustrates how the API facade orchestrates different layers of the system:
The API Facade manages the lifecycle of processing requests, from raw LDIF input to validated domain entities.
Sources: src/README.md:27-38, tests/integration/test_api_integration.py:84-98
Primary API Operations
Parsing and Writing
The API provides multiple methods for ingesting and exporting LDIF data. These operations are server-aware and can auto-detect the effective server type if not explicitly provided.
| Method | Input | Output | Description |
|---|---|---|---|
parse_ldif() | str | Result[ParseResponse] | Parses a raw LDIF string into domain entries. |
parse_ldif_file() | Path | Result[ParseResponse] | Parses LDIF content from a file path. |
write_ldif() | list[Entry] | Result[str] | Serializes domain entries back to LDIF format. |
write_ldif_file() | list[Entry], Path | Result[None] | Writes domain entries to a specified file. |
Sources: src/flext_ldif/api.py, examples/README.md:50-65, examples/01_basic_usage.py:76-90
Validation and Analytics
The library supports strict RFC-compliant validation and statistical analysis of entry sets.
The validation workflow ensures that entries meet business rules and schema constraints before further processing.
Sources: tests/integration/test_api_integration.py:77-82, examples/01_basic_usage.py:92-101
Advanced Integration Services
Server Migration and Pipelines
The API exposes specialized pipelines for handling complex transformations, such as migrating data between Oracle Internet Directory (OID) and Oracle Unified Directory (OUD).
- Migration Pipeline: Managed through
migration_pipeline(), it coordinates input/output directories and server-specific transformation settings. - Categorization: Accessible via
categorization(), it allows for logical grouping of entries (e.g., Users, Groups, ACLs) based on objectClass and base DN rules.
Sources: tests/integration/test_api_integration.py:151-177, examples/README.md:85-95
Data Models and Constants
The API provides unified access to the domain model namespace and system constants.
ldif.models: Direct access toEntry,DN,Attributes, and configuration models likeMigrateOptions.ldif.constants: Access to server types, binary attribute names, and LDAP syntaxes.
# Programmatic entry building via API-exposed models
from flext_ldif import ldif, m, c
entry = m.Ldif.Entry.create(
dn="cn=user,dc=example,dc=com",
attributes={
c.Tests.NAME_CN: ["User Name"],
"objectClass": ["person"]
}
).unwrap()
Sources: src/flext_ldif/constants.py:20-50, tests/integration/test_api_integration.py:61-75, tests/integration/test_api_integration.py:100-111
Configuration and Settings
The API is governed by FlextLdifSettings, which manages infrastructure-level configurations such as entry limits and observability integration.
| Setting | Type | Default | Description |
|---|---|---|---|
max_entries | int | 1000 | Maximum number of entries to process in a single batch. |
strict_validation | bool | True | Whether to enforce strict RFC compliance during parsing. |
enable_observability | bool | True | Enables distributed tracing and structured logging. |
encoding | str | UTF-8 | Default character encoding for file operations. |
Sources: src/README.md:77-85, examples/01_basic_usage.py:48-52
Error Handling Patterns
The API utilizes a "Railway-Oriented" pattern where operations return a Result type. This prevents deep nesting of try-except blocks and allows for clean pipeline composition.
Conclusion
The FLEXT-LDIF API provides a robust, clean interface for enterprise-grade LDIF processing. By abstracting complex LDAP server differences and providing high-level service pipelines (Migration, Categorization, Validation), it enables developers to build maintainable and type-safe directory integration tools. Its adherence to the Railway-oriented pattern ensures resilient error handling across all integration points.