# apache/airflow-client-python architecture

> Architecture diagram of the GitHub repository apache/airflow-client-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apache/airflow-client-python
- Repository: https://github.com/apache/airflow-client-python

## Overview

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: [`airflow_client/client/api_client.py`](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api_client.py) (ApiClient), [`airflow_client/client/api`](https://github.com/apache/airflow-client-python/tree/main/airflow_client/client/api) (Resource APIs), [`airflow_client/client/models`](https://github.com/apache/airflow-client-python/tree/main/airflow_client/client/models) (Models), [`airflow_client`](https://github.com/apache/airflow-client-python/tree/main/airflow_client) (Client package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["SDK core"]
  node_n3["Client package<br/>generated sdk"]
  node_n4["Configuration<br/>client settings<br/>[configuration.py]"]
  node_n5["ApiClient<br/>request orchestrator<br/>[api_client.py]"]
  node_n6["REST transport<br/>http layer<br/>[rest.py]"]
  node_n7["API response<br/>response wrapper<br/>[api_response.py]"]
  node_n8["Client errors<br/>exception types<br/>[exceptions.py]"]
  node_n9["Resource APIs<br/>endpoint modules"]
  node_n10["DAG APIs<br/>workflow endpoints<br/>[dag_api.py]"]
  node_n11["Run & task APIs<br/>execution endpoints<br/>[dag_run_api.py]"]
  node_n12["Admin APIs<br/>admin endpoints<br/>[variable_api.py]"]
  node_n13["Asset APIs<br/>asset endpoints<br/>[asset_api.py]"]
  node_n14["System APIs<br/>health/monitoring<br/>[monitor_api.py]"]
  node_n15["Models"]
end

subgraph group_g2["Contract layer"]
  node_n2["OpenAPI spec<br/>contract source<br/>[v2.yaml]"]
  node_n16["Endpoint docs<br/>generated docs"]
  node_n17["Generated tests<br/>contract tests"]
end

subgraph group_g3["Packaging"]
  node_n18["Build metadata<br/>packaging<br/>[pyproject.toml]"]
end

node_n1(("Python consumer<br/>external caller"))

node_n1 -->|"uses"| node_n3
node_n3 -->|"configures"| node_n4
node_n3 -->|"creates"| node_n5
node_n5 -->|"sends via"| node_n6
node_n5 -->|"wraps"| node_n7
node_n5 -->|"raises"| node_n8
node_n5 -->|"serializes"| node_n15
node_n5 -->|"invokes"| node_n9
node_n9 -->|"includes"| node_n10
node_n9 -->|"includes"| node_n11
node_n9 -->|"includes"| node_n12
node_n9 -->|"includes"| node_n13
node_n9 -->|"includes"| node_n14
node_n10 -->|"uses"| node_n15
node_n11 -->|"uses"| node_n15
node_n12 -->|"uses"| node_n15
node_n13 -->|"uses"| node_n15
node_n14 -->|"uses"| node_n15
node_n2 -->|"generates"| node_n3
node_n2 -->|"documents"| node_n16
node_n2 -->|"tests"| node_n17
node_n18 -->|"packages"| node_n3
node_n18 -->|"validates"| node_n17

click node_n2 "https://github.com/apache/airflow-client-python/blob/main/spec/v2.yaml"
click node_n3 "https://github.com/apache/airflow-client-python/tree/main/airflow_client"
click node_n4 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/configuration.py"
click node_n5 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api_client.py"
click node_n6 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/rest.py"
click node_n7 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api_response.py"
click node_n8 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/exceptions.py"
click node_n9 "https://github.com/apache/airflow-client-python/tree/main/airflow_client/client/api"
click node_n10 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/dag_api.py"
click node_n11 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/dag_run_api.py"
click node_n12 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/variable_api.py"
click node_n13 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/asset_api.py"
click node_n14 "https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/monitor_api.py"
click node_n15 "https://github.com/apache/airflow-client-python/tree/main/airflow_client/client/models"
click node_n16 "https://github.com/apache/airflow-client-python/tree/main/docs"
click node_n17 "https://github.com/apache/airflow-client-python/tree/main/test"
click node_n18 "https://github.com/apache/airflow-client-python/blob/main/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n3,node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n13,node_n14,node_n15 toneBlue
class node_n2,node_n16,node_n17 toneAmber
class node_n18 toneMint
class node_n1 toneNeutral
```

## Components

### SDK core

Generated client runtime and API wrappers

- [Client package](https://github.com/apache/airflow-client-python/tree/main/airflow_client): generated sdk · Top-level generated Python client package · `airflow_client`
- [Configuration](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/configuration.py): client settings · Host, auth, headers, timeout, and other settings · `airflow_client/client/configuration.py`
- [ApiClient](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api_client.py): request orchestrator · Builds requests and routes calls to the transport layer · `airflow_client/client/api_client.py`
- [REST transport](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/rest.py): http layer · Low-level HTTP request execution · `airflow_client/client/rest.py`
- [API response](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api_response.py): response wrapper · Wraps raw responses returned by the transport · `airflow_client/client/api_response.py`
- [Client errors](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/exceptions.py): exception types · Client-side error hierarchy · `airflow_client/client/exceptions.py`
- [Resource APIs](https://github.com/apache/airflow-client-python/tree/main/airflow_client/client/api): endpoint modules · Generated resource-specific REST wrappers · `airflow_client/client/api`
- [DAG APIs](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/dag_api.py): workflow endpoints · DAG metadata, parsing, source, stats, versions, warnings · `airflow_client/client/api/dag_api.py`
- [Run & task APIs](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/dag_run_api.py): execution endpoints · DAG runs, tasks, task instances, logs, dependencies, XCom · `airflow_client/client/api/dag_run_api.py`
- [Admin APIs](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/variable_api.py): admin endpoints · Variables, connections, pools, config, plugins, providers, jobs · `airflow_client/client/api/variable_api.py`
- [Asset APIs](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/asset_api.py): asset endpoints · Assets, asset events, materialization, watchers · `airflow_client/client/api/asset_api.py`
- [System APIs](https://github.com/apache/airflow-client-python/blob/main/airflow_client/client/api/monitor_api.py): health/monitoring · Health, monitor, version, login, import errors, extra links, event log · `airflow_client/client/api/monitor_api.py`
- [Models](https://github.com/apache/airflow-client-python/tree/main/airflow_client/client/models): data 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](https://github.com/apache/airflow-client-python/blob/main/spec/v2.yaml): contract source · Source of truth for the generated client · `spec/v2.yaml`
- [Endpoint docs](https://github.com/apache/airflow-client-python/tree/main/docs): generated docs · Markdown references for APIs and models · `docs`
- [Generated tests](https://github.com/apache/airflow-client-python/tree/main/test): contract tests · Per-model and per-API tests plus live smoke test · `test`

### Packaging

Project metadata and release support

- [Build metadata](https://github.com/apache/airflow-client-python/blob/main/pyproject.toml): packaging · Project and release configuration for the generated package · `pyproject.toml`

### Other components

- **Python consumer**: external caller · User code that imports and uses the SDK

## Connections

- 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
