REST API and OpenAPI Clients

Purpose and Scope

Airflow exposes management capabilities through a stable REST API so operators, platform teams, and automation scripts can work with Airflow objects without driving the web UI. The Python client documentation frames the API around resources in the Airflow metadata database, where each resource represents one kind of managed object and the endpoints are organized around those resource names. Most endpoints exchange JSON, so callers should expect to send JSON request bodies and receive JSON responses, with content negotiation headers set accordingly. Sources: clients/python/README.md

The OpenAPI client area exists to turn that REST surface into distributable language clients. In this repository, the checked-in client documentation identifies Python as the supported generated client language and explains that the generated client source itself is not committed here. Instead, Airflow release tooling produces the package artifacts and stores generated Python client code in the dedicated Airflow Client Python repository when the package is released. This separation keeps the main repository focused on API definitions and release automation rather than large generated trees. Sources: clients/README.md

At runtime, the API server entry point is a FastAPI application. Before importing Airflow internals, the module marks the process context as server, which matters because plugins loaded during import need the appropriate secrets backend chain. The same entry point creates the application by calling the cached application factory and passes an application selection from an environment variable, defaulting to all apps. That small file is important because it connects the generated OpenAPI story to the real server process that serves API routes. Sources: airflow-core/src/airflow/api_fastapi/main.py

Relevant Source Files

• clients/README.md - Describes the Airflow OpenAPI client package area, supported generated client languages, release command, packaging tools, and where generated Python client code is published.
• clients/python/README.md - Documents the generated Python client’s REST API conventions: JSON input and output, resource naming, CRUD behavior, pagination parameters, field naming, and update masks.
• airflow-core/src/airflow/api_fastapi/main.py - Provides the FastAPI application entry point used by the API server, including server process context setup, Python debug-mode warning behavior, and application selection through AIRFLOW_API_APPS.

System-to-Code Mapping

The client documentation and the server entry point serve different readers but describe one system boundary. The Python client README explains how callers should think about REST resources, request methods, response codes, and naming conventions. The OpenAPI clients README explains how maintainers generate and package client code from the API contract. The FastAPI entry point shows where that contract is served in a running Airflow API server process. Taken together, they map author-facing API semantics, release-facing client generation, and runtime-facing application startup into a single workflow. Sources: clients/README.md, clients/python/README.md, airflow-core/src/airflow/api_fastapi/main.py

API Design Conventions

The Python client README defines a resource as a single type of Airflow metadata object. Resource names are typically plural and expressed in camelCase, and the same names appear in endpoint URLs, API parameters, and responses. Field names, by contrast, are snake_case. This distinction is useful when debugging generated clients because path segments and parameter names may look different from JSON object attributes. A caller working with pools, connections, DAG runs, or similar resources should therefore separate endpoint naming rules from payload field naming rules. Sources: clients/python/README.md

CRUD behavior follows familiar HTTP method conventions, with documented exceptions possible for special endpoints. Creating a resource is typically a POST with required metadata in the request body and a successful creation response containing the resource metadata and internal identifier. Reading uses GET either for a specific resource or for a list, and list-style GET requests commonly support pagination. Updates usually use PATCH with the resource identifier and only the fields being modified. Deletes use DELETE and typically return no content on success. Sources: clients/python/README.md

Compact REST reference:

Common request headers:

Content-type: application/json
Accept: application/json

Example list shape from the documented conventions:

/api/v2/connections?limit=25&offset=25

The documented pagination parameters are straightforward but operationally important. The limit parameter caps the maximum number of objects returned and is usually twenty-five by default, while offset determines where the next slice begins. Generated clients often hide some request construction, but they still reflect the API contract. When integrating Airflow with inventory sync jobs, admin dashboards, or audit tooling, design list calls as paginated scans rather than assuming that one request returns every object. This keeps automation compatible with server-side page limits and future growth. Sources: clients/python/README.md

OpenAPI Client Generation Flow

The release workflow for the Python client is intentionally command-driven. From the Airflow source root, maintainers use Breeze release-management tooling to prepare the Python client and select the distribution format. The README states that the client source generation uses an OpenAPI generator image, while package generation uses Hatch. By default, packaging runs in a dockerized Hatch environment; a local Hatch environment can be selected when needed. This makes the generation path reproducible for releases while still allowing local packaging during development or troubleshooting. Sources: clients/README.md

breeze release-management prepare-python-client --distribution-format both

breeze release-management prepare-python-client --distribution-format both --use-local-hatch

Because generated source is not committed to the main Airflow repository, contributors should avoid looking for checked-in Python client modules here as the source of truth. The durable inputs are the API implementation and OpenAPI generation process; the generated output is published separately as part of the client release. That has a practical consequence for changes: API behavior should be reviewed where the server defines and serves it, while client packaging issues should be reproduced through the release command. Sources: clients/README.md, airflow-core/src/airflow/api_fastapi/main.py

Runtime Entry Point and Configuration

The FastAPI entry point performs two startup-sensitive actions before exposing the application object. First, it sets an internal process-context environment value to server before other Airflow imports, so import-time plugin behavior sees the correct server-side context. Second, on Python versions at least 3.12, it warns when asynchronous debug mode or Python development mode is enabled because of a documented uvloop incompatibility risk. These checks are not client APIs, but they explain why a local API server can behave differently under debug-oriented environment settings. Sources: airflow-core/src/airflow/api_fastapi/main.py

The same module constructs the exported app by calling the cached application factory with an apps argument. The value comes from AIRFLOW_API_APPS and defaults to all. The source comment explains why this is environment-driven: the FastAPI development command cannot receive the app selection as an additional argument. For operators and developers, this means API surface selection is part of process configuration, while generated clients should be treated as clients for the public API contract they were generated against. Sources: airflow-core/src/airflow/api_fastapi/main.py

Practical Next Steps

Use the Python client README when you need request-shape expectations, naming rules, CRUD behavior, pagination, and update-mask conventions. Use the OpenAPI clients README when you are preparing or validating generated package artifacts. Use the FastAPI entry point when diagnosing API-server startup behavior, especially process context, environment-controlled app selection, or Python debug-mode warnings. For adjacent topics, read the API authentication page before exposing the API to users, and read airflowctl documentation when you want a command-line interface that talks to Airflow through the REST API.