How apache/airflow-client-python works
1. This repository is an autogenerated Python client SDK for the Apache Airflow REST API, not an Airflow server or business-logic application. Its only runtime dependency is a live Airflow deployment exposing the /api/v2 endpoints.
2. The OpenAPI contract is the source of truth. spec/v2.yaml defines the API schema, and the generated airflow_client/ package plus docs/ markdown files are derived from it. The README explicitly states the client was generated with OpenAPI Generator.
3. The client runtime is centered in airflow_client/client/:
- configuration.py holds host, auth, headers, timeout and other client settings.
- api_client.py is the request orchestrator.
- rest.py is the HTTP transport layer.
- api_response.py wraps returned responses.
- exceptions.py defines client-side error types.
4. The API surface is split by Airflow resource, with one module per domain in airflow_client/client/api/. The major subsystems are DAGs, DAG runs, task instances, variables, connections, pools, assets, backfills, configuration, jobs, plugins, providers, logs, import errors, and health/monitoring. Each class maps directly to a set of REST endpoints for that resource.
5. The data model layer lives in airflow_client/client/models/. These classes represent request bodies, response payloads, enums, nested structures, and list wrappers. They are used for JSON serialization/deserialization so API methods can return typed objects instead of raw dictionaries.
6. The main data flow is: user code creates a Configuration, then an ApiClient, then a resource-specific API object, and finally calls an endpoint method. The client serializes path/query/body parameters into an HTTP request, sends it to Airflow, and deserializes JSON responses into the generated model classes or response wrappers.
7. Authentication is a boundary between this client and the Airflow deployment. The README documents support for basic auth, bearer tokens, Google OpenID, Kerberos, and OAuth2 password bearer. The client itself does not authenticate users; it only forwards the configured credentials to the server.
8. The API is organized around Airflow’s CRUD conventions. Most endpoints follow predictable patterns like list/get/create/patch/delete, with pagination via limit and offset, and partial updates via update_mask. The client mirrors those conventions in method names and request-body models.
9. Several endpoint families represent higher-level Airflow behavior rather than simple metadata reads: triggering and clearing DAG runs, backfilling, materializing assets, fetching task logs, querying task dependencies/tries, and manipulating XCom entries. These are the main “workflow” operations exposed by the SDK.
10. The repository also includes generated documentation and test coverage as part of the contract. docs/ contains endpoint and model references, while test/ contains one test file per generated API/model, plus test_python_client.py for smoke-testing against a real Airflow instance.
11. Build and release concerns are lightweight because this is a generated package. pyproject.toml, uv.lock, version.txt, and the GitHub Actions workflows support packaging, validation, and regression checks; there is no application deployment topology beyond publishing/installing the Python package.
12. For an architecture diagram, the key boundary is external: Python consumers call this SDK, and the SDK talks over HTTP/JSON to an Airflow webserver API. Internally, the package is a thin layered stack: generated API wrappers on top of a shared HTTP client, backed by generated models and error handling.
Main entry points: api_client.py ApiClient · api Resource APIs · models Models · airflow_client Client package
Components 18
SDK core
Generated client runtime and API wrappers
- Client package · Top-level generated Python client package
airflow_client - Configuration · Host, auth, headers, timeout, and other settings
airflow_client/client/configuration.py - ApiClient · Builds requests and routes calls to the transport layer
airflow_client/client/api_client.py - REST transport · Low-level HTTP request execution
airflow_client/client/rest.py - API response · Wraps raw responses returned by the transport
airflow_client/client/api_response.py - Client errors · Client-side error hierarchy
airflow_client/client/exceptions.py - Resource APIs · Generated resource-specific REST wrappers
airflow_client/client/api - DAG APIs · DAG metadata, parsing, source, stats, versions, warnings
airflow_client/client/api/dag_api.py - Run & task APIs · DAG runs, tasks, task instances, logs, dependencies, XCom
airflow_client/client/api/dag_run_api.py - Admin APIs · Variables, connections, pools, config, plugins, providers, jobs
airflow_client/client/api/variable_api.py - Asset APIs · Assets, asset events, materialization, watchers
airflow_client/client/api/asset_api.py - System APIs · Health, monitor, version, login, import errors, extra links, event log
airflow_client/client/api/monitor_api.py - Models · Generated request and response classes used for JSON mapping
airflow_client/client/models
Contract layer
OpenAPI source plus generated docs and tests
- OpenAPI spec · Source of truth for the generated client
spec/v2.yaml - Endpoint docs · Markdown references for APIs and models
docs - Generated tests · Per-model and per-API tests plus live smoke test
test
Packaging
Project metadata and release support
- Build metadata · Project and release configuration for the generated package
pyproject.toml
Other components
- Python consumer · User code that imports and uses the SDK
Connections 23
- Python consumer → Client package: uses · Consumers import the generated SDK
- Client package → Configuration: configures · Client setup starts with configuration
- Client package → ApiClient: creates · ApiClient is the central request coordinator
- ApiClient → REST transport: sends via · Requests are executed by the HTTP transport
- ApiClient → API response: wraps · Transport responses are wrapped for callers
- ApiClient → Client errors: raises · Failures surface as client exceptions
- ApiClient → Models: serializes · Parameters and bodies are encoded from models
- ApiClient → Resource APIs: invokes · Resource APIs delegate through the shared client
- Resource APIs → DAG APIs: includes · DAG-related endpoint modules
- Resource APIs → Run & task APIs: includes · Run and task execution endpoint modules
- Resource APIs → Admin APIs: includes · Admin and configuration endpoint modules
- Resource APIs → Asset APIs: includes · Asset endpoint modules
- Resource APIs → System APIs: includes · Health and system endpoint modules
- DAG APIs → Models: uses · DAG methods exchange typed payloads
- Run & task APIs → Models: uses · Execution methods exchange typed payloads
- Admin APIs → Models: uses · Admin methods exchange typed payloads
- Asset APIs → Models: uses · Asset methods exchange typed payloads
- System APIs → Models: uses · System endpoints also map to generated models
- OpenAPI spec → Client package: generates · The OpenAPI contract drives client generation
- OpenAPI spec → Endpoint docs: documents · Docs mirror the contract schema and endpoints
- OpenAPI spec → Generated tests: tests · Generated tests validate the contract surface
- Build metadata → Client package: packages · Project metadata packages the generated library
- Build metadata → Generated tests: validates · CI and packaging support regression checks